Documenting your API

Each instance of Pulp hosts dynamically generated REST API documentation located at http://pulpserver/pulp/api/v3/docs/.

The documentation is generated using ReDoc based on the OpenAPI 3.0 schema generated by Pulp. The schema generator iterates over all the Views and Viewsets in every plugin and generates the schema based on the information provided by Viewset doc strings, Viewset method docstrings, associated Model's names, View docstrings, and the help text from serializers.

Individual parameters and responses are documented automatically based on the Serializer field type. A field's description is generated from the "help_text" kwarg when defining serializer fields.

Response status codes can be generated through the Meta class on the serializer:

from rest_framework.status import HTTP_400_BAD_REQUEST

class SnippetSerializerV1(serializers.Serializer):
    title = serializers.CharField(required=False, allow_blank=True, max_length=100)

    class Meta:
        error_status_codes = {
            HTTP_400_BAD_REQUEST: 'Bad Request'
        }

You may disable schema generation for a view by setting schema to None:

class CustomView(APIView):
    # ...
    schema = None  # Will not appear in schema

Note

Meta.ref_name is a string that is used as the model definition name for the serializer class. If this attribute is not specified, all serializers have an implicit name derived from their class name. In order to avoid possible name collisions between plugins, plugins must define ref_name on the Meta class using <app_label>. as a prefix.

For the model based serializers offered by pulpcore (i.e. pulpcore.plugin.serializers.ModelSerializer and derived serializers), Meta.ref_name will be set correctly automatically. There is no need to set Meta.ref_name in this case.

If a serializer has no associated model, you need to set Meta.ref_name explicitly. For example, if the SnippetSerializerV1 from above is for the plugin providing the snippets app, ref_name could be set like this:

class SnippetSerializerV1(serializers.Serializer):
    title = serializers.CharField(required=False, allow_blank=True, max_length=100)

    class Meta:
        ref_name = "snippets.Snippet"

Note

Plugin authors can provide manual overrides using the @extend_schema decorator

The OpenAPI schema for pulpcore and all installed plugins can be downloaded from the pulp-api server:

curl -o api.json http://localhost:24817/pulp/api/v3/docs/api.json

The OpenAPI schema for a specific plugin can be downloaded by specifying the plugin's module name as a GET parameter. For example for pulp_rpm only endpoints use a query like this:

curl -o api.json http://localhost:24817/pulp/api/v3/docs/api.json?component=rpm

OpenAPI Tags

Tags are used to group operations logically into categories, such as RepositoriesRpm, DistributionsRpm, ContentPackages, and so on. Pulpcore OpenAPI Tags are generated from URL paths.

Path /pulp/api/v3/repositories/rpm/rpm/ yields the tag repositories: rpm which is turned into RepositoriesRpmApi in the bindings client.

It is possible to customize the tag by setting the pulp_tag_name attribute at your view.

Setting pulp_tag_name = "Pulp: RPM Repo" at RpmRepositoryViewSet yields the tag Pulp: RPM Repo which is turned into PulpRPMRepoApi in the bindings client.