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 <https://github.com/Rebilly/ReDoc>`_ based on the
`OpenAPI 3.0 <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md>`_ 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:

.. code-block:: python

    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``:

.. code-block:: python

    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.
    :class:`~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
    <https://drf-spectacular.readthedocs.io/en/stable/drf_spectacular.html#drf_spectacular.utils.extend_schema>`_

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

.. code-block:: bash

    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:

.. code-block:: bash

    curl -o api.json http://localhost:24817/pulp/api/v3/docs/api.json?plugin=pulp_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.