drf-openapi3 0.1.24

Manage OpenApi documentation with DRF

DRF OpenApi 3

OpenApi 3 utility for Django REST Framework

Enhances DRF AutoSchema and SchemaGenerator to help generating a better OpenApi 3 documentation.

Supports servers, deprecated and summary in schema generation, now you mark them as deprecated and display the summary besides the description. If you want your ApiView to display custom content in the documentation, you can add it by writing comments to the view/view method in YAML format. Fixed request body and responses for views that handle multiple objects, such as bulk insert, bulk update and bulk delete. Now they are displayed as array.

Installation

1. Install the package using pip install drf_openapi3
2. Add drf_openapi3.apps.OpenApi3Config to Django INSTALLED_APPS

Configuration

1. OpenApi documentation View

Extend drf_openapi3.views.OpenApiTemplateView. You can define a title and template name, otherwise default values will be used.

from django.contrib.auth.mixins import LoginRequiredMixin
from drf_openapi3.views import OpenApiTemplateView


class MyOpenApiTemplateView(LoginRequiredMixin, OpenApiTemplateView):
    title = 'My OpenAPI'
    template_name = 'path/to/mytemplate.html'

2. Add schema to urlpatterns using drf_openapi3.AdvancedSchemaGenerator as generator class

from django.contrib.auth.decorators import login_required
from django.urls import path
from drf_openapi3.schemas.advanced import AdvancedSchemaGenerator
from rest_framework.schemas import get_schema_view


urlpatterns = [
    # Use the `get_schema_view()` helper to add a `SchemaView` to project URLs.
    #   * `title` and `description` parameters are passed to `SchemaGenerator`.
    #   * Provide view name for use with `reverse()`.
    path('my-schema/', login_required(
        get_schema_view(
            title='My API',
            description='My API description',
            version='1.0.0',
            generator_class=AdvancedSchemaGenerator,
            public=True,
        ),
        login_url='/accounts/login/',
    ), name='my_schema_name'),
    # ...
    # ...
]

3. Start writing your ApiViews.

from rest_framework.generics import ListAPIView


class MyAPIListView(ListAPIView):
    allowed_methods = ['get']

    def get(self, request, *args, **kwargs):
        return super(MyAPIListView, self).list(request, *args, **kwargs)

How to use

Let's see step by step what you can do.

Define multiple servers

Useful for instance if you provide a test sandbox together with a production server. In Django settings you can define url and description in API_SERVERS:

API_SERVERS = [
    {
        "url": "https://test.example.com/",
        "description": "Sandbox server (uses test data)",
    },
    {
        "url": "https://example.com/",
        "description": "Production server (uses live data)",
    },
]

If you don't define anything, Django BASE_URL will be used to build your server block. So if you are developing in local environment, the server url will be http://localhost:8000. If it's production environment, the server url will be https://example.com. Keep in mind that defining multiple servers in API_SERVERS will allow users to switch server urls in the dropdown on the documentation before testing your endpoints.

Apply tags to your ApiView

If you want to tag your view, just pass tags to your view schema. Default is "api". You can decide your own, it can come in handy to add the endpoint version:

from drf_openapi3.schemas.advanced import AdvancedAutoSchema
from rest_framework.generics import ListAPIView


class MyAPIListView(ListAPIView):
    # ...
    # ...
    allowed_methods = ['get']
    schema = AdvancedAutoSchema(
        tags=["v0"],
        component_name="My",
        operation_id_base="MyAPI",
        handles_many_objects=True
    )

    def get(self, request, *args, **kwargs):
        return super(MyAPIListView, self).list(request, *args, **kwargs)

Apply deprecated to your old ApiView

If you want to mark your view as deprecated, just add the attribute deprecated = True to your view schema:

from drf_openapi3.schemas.advanced import AdvancedAutoSchema
from rest_framework.generics import ListAPIView


class MyAPIListView(ListAPIView):
    # ...
    # ...
    allowed_methods = ['get']
    schema = AdvancedAutoSchema(
        tags=["v0"],
        component_name="My",
        operation_id_base="MyAPI",
        handles_many_objects=True,
        deprecated=True
    )

    def get(self, request, *args, **kwargs):
        return super(MyAPIListView, self).list(request, *args, **kwargs)

Views that handle multiple objects with methods besides GET

When you write a view that performs bulk create, update or delete operations you face some issues on the documentation:

the responses field schema types are object, but they should be array.

By adding handles_many_objects=True attribute to your view schema, you tell the schema that responses must be array.

from drf_openapi3.schemas.advanced import AdvancedAutoSchema
from rest_framework.generics import ListCreateAPIView
from rest_framework.response import Response
from rest_framework.status import HTTP_400_BAD_REQUEST, HTTP_200_OK



class MyListPostView(ListCreateAPIView):
    # ...
    # ...
    allowed_methods = ['get', 'post']
    schema = AdvancedAutoSchema(
        tags=["v0"],
        component_name="My",
        operation_id_base="MyAPI",
        handles_many_objects=True,
    )

    def post(self, request, *args, **kwargs) -> Response:
        serialized = self.get_serializer(data=request.data, many=True)
        if serialized.is_valid():
            serialized.save()
            return Response(serialized.data, status=HTTP_200_OK)
        return Response(serialized.errors, status=HTTP_400_BAD_REQUEST)

Display custom content in the documentation

DRF AutoSchema already reads your view/view method Docstring:

if you want to display the endpoint description in your documentation, you can write some text in the view/view method Docstring.

That wasn't enough for me though.

Let's start with the simplest one, the same one that's already implemented from DRF AutoSchema that it has been kept to have backwards compatibility:

we add a plain description in the view Docstring. If we do it on both view and method view, only method view Docstring will be taken into account:

from drf_openapi3.schemas.advanced import AdvancedAutoSchema
from rest_framework.generics import ListCreateAPIView
from rest_framework.response import Response
from rest_framework.status import HTTP_400_BAD_REQUEST, HTTP_200_OK


class MyListPostView(ListCreateAPIView):
    """
    This is my endpoint description and it will be reported 
    for each allowed method.
    """
    # ...
    # ...
    allowed_methods = ['get', 'post']
    schema = AdvancedAutoSchema(
        tags=["v0"],
        component_name="My",
        operation_id_base="MyListPost",
        handles_many_objects=True,
    )   

    def post(self, request, *args, **kwargs) -> Response:
        """
        ... and that's my method description
        Since both the descriptions are defined you'll see only this one.
        You won't see "This is my endpoint description", 
        unless you delete the text here above.
        """
        serialized = self.get_serializer(data=request.data, many=True)
        if serialized.is_valid():
            serialized.save()
            return Response(serialized.data, status=HTTP_200_OK)
        return Response(serialized.errors, status=HTTP_400_BAD_REQUEST)

If you want to manage custom changes to your schema, just add them to the Docstring in YAML format. You'll notice that it'll be easier for you to read your code too.

By default DRF AutoSchema displays only status code 200 as example response. Since 400, 401, 403, 404 status codes return a JSON {"detail": <error detail>}, in Django settings you can define STATIC_ERROR_CODES = True to display more responses in your documentation. If you have to perform further changes on responses in your view, you can put them in YAML view/view method Docstring.

If you want to limit the allowed response codes that you're going to see on the documentation, just list the allowed status codes in your view (allowed_status_codes); this is useful when you had enabled STATIC_ERROR_CODES and you want to prevent some responses to be displayed.

We're getting creative here, let's add a complete example:

from drf_openapi3.schemas.advanced import AdvancedAutoSchema
from rest_framework.generics import ListAPIView, CreateAPIView, UpdateAPIView, DestroyAPIView


class MyCommentedView(ListAPIView, CreateAPIView, UpdateAPIView, DestroyAPIView):
    """
        get:
            summary: Summary for get method
            description: Description for get method
        post:
            summary: Summary for post method
            description: Description for post method
            400:
                description: Invalid object, that's a custom description of 400 response code for post method
        put:
            summary: Summary for put method
            description: Description for put method
        delete:
            summary: Summary for delete method
            description: Description for delete method
            200:
                description: Corsa objects deleted, that's a custom description of 200 response code for delete method
                schema:
                    type: array
                    items:
                        properties:
                            field:
                                type: boolean
                                description: Deleted flag, here we define a different schema for bulk delete
    """
    allowed_methods = ("GET", "POST", "PUT", "DELETE")
    allowed_status_codes = (200, 400, 401, 403)

    schema = AdvancedAutoSchema(
        tags=["v0"],
        component_name="MyCommented",
        operation_id_base="MyCommentedWriteDelete",
        handles_many_objects=True,
    )

# ...
# ...

If you've overridden the view methods already (.get(), .post(), .put(), .delete()) you can write there your comments. Please be advised that if you do so you must not use the notation method: properties:

from rest_framework.generics import ListAPIView, DestroyAPIView
from rest_framework.response import Response
from rest_framework.status import HTTP_200_OK


class MyCommentedView(ListAPIView, DestroyAPIView):

    def delete(self, request, *args, **kwargs) -> Response:
        """
        summary: Summary for delete method
        description: Description for delete method
        200:
            description: Corsa objects deleted, that's a custom description of 200 response code for delete method
            schema:
                type: array
                items:
                    properties:
                        field:
                            type: boolean
                            description: Deleted flag, here we define a different schema for bulk delete
        """
        output = []
        for data in request.data:
            # ...
            # ...
            pass
        return Response(output, status=HTTP_200_OK)

Last but not least: do you want to set a default sort for your endpoints? Just pass index=n to AdvancedAutoSchema:

from drf_openapi3.schemas.advanced import AdvancedAutoSchema
from rest_framework.generics import ListAPIView, ListCreateAPIView


class MyAPIListView(ListAPIView):
    # ...
    # ...
    allowed_methods = ['get']
    schema = AdvancedAutoSchema(
        index=0,
        tags=["v0"],
        component_name="My",
        operation_id_base="MyAPI",
        handles_many_objects=True,
        deprecated=True
    )


class MyListPostView(ListCreateAPIView):
    """
    This is my endpoint description and it will be reported 
    for each allowed method.
    """
    # ...
    # ...
    allowed_methods = ['get', 'post']
    schema = AdvancedAutoSchema(
        index=1,
        tags=["v0"],
        component_name="My",
        operation_id_base="MyListPost",
        handles_many_objects=True,
    )