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.
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?plugin=pulp_rpm