Схема

Теперь, когда у нас есть готовый API, нам нужен способ быстро и точно документировать его функциональность для других.

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

Схема - это машиночитаемый документ, в котором описаны все доступные конечные точки API, URL-адреса и HTTP-запросы (GET, POST, PUT, DELETE и т.д.). Это здорово, но не очень удобно для чтения человеком. Поэтому вводим документацию, которая представляет собой нечто, добавленное в схему, что облегчает ее чтение для человека.

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

Спецификация OpenAPI является текущим стандартным способом документирования API. Она описывает общие правила формата для доступных конечных точек, входов, методов аутентификации, контактной информации и многое другое.

На момент написания этого курса drf-spectacular является рекомендуемым сторонним пакетом для генерации схемы OpenAPI для Django REST Framework.

Чтобы начать, установите drf-spectacular с помощью Pip, обычным способом:

pip install drf-spectacular

Добавьте его в конфигурацию INSTALLED_APPS в файле mysite/settings.py:

INSTALLED_APPS = [
...
...
    # API
    'rest_framework',
    'blog_api.apps.BlogApiConfig',
    'django_filters',
    'rest_framework.authtoken',
    'drf_spectacular', # new
]

Затем зарегистрируйте drf-spectacular в секции REST_FRAMEWORK:

REST_FRAMEWORK = {
    "DEFAULT_PERMISSION_CLASSES": [
        "rest_framework.permissions.IsAuthenticated",
    ],
    'DEFAULT_FILTER_BACKENDS': ['django_filters.rest_framework.DjangoFilterBackend'],

    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.LimitOffsetPagination',
    'PAGE_SIZE': 5,

    'DEFAULT_AUTHENTICATION_CLASSES': (
        'rest_framework.authentication.SessionAuthentication',
        "rest_framework.authentication.TokenAuthentication",
    ),
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',  # new
}

Последним шагом является добавление некоторых метаданных, таких как название, описание и версия. В mysite/settings.py и добавьте следующее:

SPECTACULAR_SETTINGS = {
    "TITLE": "Blog API Project",
    "DESCRIPTION": "A sample blog to learn about DRF",
    "VERSION": "1.0.0",
    # OTHER SETTINGS
}

Чтобы сгенерировать схему как отдельный файл, мы можем использовать команду управления и указать имя файла, которым будет schema.yml:

python manage.py spectacular --file schema.yml

В корневом каталоге проекта был создан новый файл schema.yml:

Если вы откроете этот файл в вашем текстовом редакторе, он довольно длинный и не очень удобный для человека.

Динамическая схема

Более динамичный подход заключается в предоставлении схемы непосредственно из нашего API в виде URL-маршрута. Мы для этого импортируем SpectacularAPIView и добавим новый URL путь по адресу api/schema/, чтобы отобразить её. Для этого в blog_api/urls.py добавим следующий код:

from django.urls import path, re_path
from .views import PostList, PostDetail, UserPostList
from drf_spectacular.views import SpectacularAPIView # new

urlpatterns = [
    path("<int:pk>/", PostDetail.as_view(), name="post_detail"),
    path("", PostList.as_view(), name="post_list"),
    re_path('^user/(?P<username>.+)/$', UserPostList.as_view()),
    path("schema/", SpectacularAPIView.as_view(), name="schema"),  # new
]

Запустите локальный сервер с помощью команды:

python manage.py runserver

И перейдите к новой схеме. URL конечной точки по адресу http://127.0.0.1:8000/api/schema/. Автоматически сгенерированный файл схемы всего нашего API доступен и будет загружен в виде файла.

Лично я предпочитаю динамический подход в проектах, а не необходимость заново генерировать файл schema.yml при каждом изменении API.