Встроенная документация по API

Встроенная документация по API включает:

  • Документация конечных точек API.

  • Автоматически генерируемые примеры кода для каждой из доступных клиентских библиотек API.

  • Поддержка взаимодействия с API.

Установка

Библиотека coreapi требуется в качестве зависимости для документации API. Обязательно установите последнюю версию. Библиотеки Pygments и Markdown являются необязательными, но рекомендуемыми.

Чтобы установить документацию API, вам нужно включить ее в URLconf вашего проекта:

from rest_framework.documentation import include_docs_urls

urlpatterns = [
    ...
    path('docs/', include_docs_urls(title='My API title'))
]

Это будет включать в себя два различных вида:

  • /docs/ - Сама страница документации.

  • /docs/schema.js - Ресурс JavaScript, раскрывающий схему API.

Примечание : По умолчанию include_docs_urls конфигурирует базовый SchemaView для генерации публичных схем. Это означает, что представления не будут инстанцироваться с экземпляром request. Т.е. внутри представления self.request будет None.

Чтобы быть совместимыми с таким поведением, методы (такие как get_serializer или get_serializer_class и т.д.), которые проверяют self.request или, в частности, self.request.user, могут быть скорректированы для обработки этого случая.

Вы можете обеспечить представление экземпляром request, вызывая include_docs_urls с public=False :

from rest_framework.documentation import include_docs_urls

urlpatterns = [
    ...
    # Generate schema with valid `request` instance:
    path('docs/', include_docs_urls(title='My API title', public=False))
]

Документирование ваших взглядов

Вы можете документировать свои представления, включив в них docstrings, описывающие каждое из доступных действий. Например:

class UserList(generics.ListAPIView):
    """
    Return a list of all the existing users.
    """

Если представление поддерживает несколько методов, следует разделить документацию с помощью разделителей в стиле method:.

class UserList(generics.ListCreateAPIView):
    """
    get:
    Return a list of all the existing users.

    post:
    Create a new user instance.
    """

При использовании наборов представлений следует использовать соответствующие имена действий в качестве разделителей.

class UserViewSet(viewsets.ModelViewSet):
    """
    retrieve:
    Return the given user.

    list:
    Return a list of all the existing users.

    create:
    Create a new user instance.
    """

Пользовательские действия над наборами представлений также можно документировать аналогичным образом, используя имена методов в качестве разделителей или присоединяя документацию к методам отображения действий.

class UserViewSet(viewsets.ModelViewset):
    ...

    @action(detail=False, methods=['get', 'post'])
    def some_action(self, request, *args, **kwargs):
        """
        get:
        A description of the get method on the custom action.

        post:
        A description of the post method on the custom action.
        """

    @some_action.mapping.put
    def put_some_action():
        """
        A description of the put method on the custom action.
        """

documentation API Reference

Модуль rest_framework.documentation предоставляет три вспомогательные функции для настройки интерактивной документации API, include_docs_urls (использование показано выше), get_docs_view и get_schemajs_view.

include_docs_urls использует get_docs_view и get_schemajs_view для генерации шаблонов url для страницы документации и ресурса JavaScript, который раскрывает схему API соответственно. Они предоставляют следующие опции для настройки. (** get_docs_view и get_schemajs_view в конечном итоге вызывают rest_frameworks.schemas.get_schema_view() , см. док-ты по схемам для получения дополнительной информации).

include_docs_urls

  • title : По умолчанию None. Может использоваться для предоставления описательного заголовка для определения схемы.

  • description : По умолчанию None. Может использоваться для предоставления описания для определения схемы.

  • schema_url : По умолчанию None. Может использоваться для передачи канонического базового URL для схемы.

  • public : По умолчанию True. Следует ли считать схему публичной*? Если True схема генерируется без request экземпляра, передаваемого представлениям.

  • patterns : По умолчанию None. Список URL, которые необходимо проверить при генерации схемы. Если None, то будет использоваться URL conf проекта.

  • generator_class : По умолчанию rest_framework.schemas.SchemaGenerator. Может использоваться для указания подкласса SchemaGenerator, который будет передан в SchemaView.

  • authentication_classes : По умолчанию api_settings.DEFAULT_AUTHENTICATION_CLASSES. Может использоваться для передачи пользовательских классов аутентификации в SchemaView.

  • permission_classes : По умолчанию api_settings.DEFAULT_PERMISSION_CLASSES Может использоваться для передачи пользовательских классов разрешений в SchemaView.

  • renderer_classes : По умолчанию None. Может использоваться для передачи пользовательских классов рендеринга в SchemaView.

get_docs_view

  • title : По умолчанию None. Может использоваться для предоставления описательного заголовка для определения схемы.

  • description : По умолчанию None. Может использоваться для предоставления описания для определения схемы.

  • schema_url : По умолчанию None. Может использоваться для передачи канонического базового URL для схемы.

  • public : По умолчанию True. Если True схема генерируется без request экземпляра, передаваемого представлениям.

  • patterns : По умолчанию None. Список URL, которые необходимо проверить при генерации схемы. Если None, то будет использоваться URL conf проекта.

  • generator_class : По умолчанию rest_framework.schemas.SchemaGenerator. Может использоваться для указания подкласса SchemaGenerator, который будет передан в SchemaView.

  • authentication_classes : По умолчанию api_settings.DEFAULT_AUTHENTICATION_CLASSES. Может использоваться для передачи пользовательских классов аутентификации в SchemaView.

  • permission_classes : По умолчанию api_settings.DEFAULT_PERMISSION_CLASSES. Может использоваться для передачи пользовательских классов разрешений в SchemaView.

  • renderer_classes : По умолчанию None. Может использоваться для передачи пользовательских классов рендереров в SchemaView. Если None, SchemaView будет сконфигурирован с DocumentationRenderer и CoreJSONRenderer рендерами, соответствующими (по умолчанию) html и corejson форматам.

get_schemajs_view

  • title : По умолчанию None. Может использоваться для предоставления описательного заголовка для определения схемы.

  • description : По умолчанию None. Может использоваться для предоставления описания для определения схемы.

  • schema_url : По умолчанию None. Может использоваться для передачи канонического базового URL для схемы.

  • public : По умолчанию True. Если True схема генерируется без request экземпляра, передаваемого представлениям.

  • patterns : По умолчанию None. Список URL, которые необходимо проверить при генерации схемы. Если None, то будет использоваться URL conf проекта.

  • generator_class : По умолчанию rest_framework.schemas.SchemaGenerator. Может использоваться для указания подкласса SchemaGenerator, который будет передан в SchemaView.

  • authentication_classes : По умолчанию api_settings.DEFAULT_AUTHENTICATION_CLASSES. Может использоваться для передачи пользовательских классов аутентификации в SchemaView.

  • permission_classes : По умолчанию api_settings.DEFAULT_PERMISSION_CLASSES Может использоваться для передачи пользовательских классов разрешений в SchemaView.

Настройка примеров кода

Встроенная документация по API включает автоматически сгенерированные примеры кода для каждой из доступных клиентских библиотек API.

Вы можете настроить эти примеры, подклассифицировав DocumentationRenderer , установив languages в список языков, которые вы хотите поддерживать:

from rest_framework.renderers import DocumentationRenderer


class CustomRenderer(DocumentationRenderer):
    languages = ['ruby', 'go']

Для каждого языка вам необходимо предоставить шаблон intro, в котором подробно описаны инструкции по установке и т.п., а также общий шаблон для выполнения API-запросов, который можно заполнить деталями индивидуального запроса. Примеры смотрите в templates for the bundled languages.

Вернуться на верх