Документация

Схема хороша для использования компьютером, но люди обычно предпочитают документацию для использования API.

В drf-spectacular поддерживаются два инструмента документирования API: Redoc и SwaggerUI.
К счастью, преобразование нашей схемы в любой из них является относительно безболезненный процесс.

Чтобы добавить Redoc, импортируйте SpectacularRedocView в верхней части blog_api/urls.py, а затем добавьте URL-путь по адресу api/schema/redoc/:

from django.urls import path, re_path
from .views import PostList, PostDetail, UserPostList
from drf_spectacular.views import SpectacularAPIView, SpectacularRedocView  # 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"),
    path("schema/redoc/", SpectacularRedocView.as_view(url_name="schema"), name="redoc")  # new
]

Если локальный сервер все еще работает, вы можете перейти по адресу http://127.0.0.1:8000/api/schema/redoc/ чтобы ознакомиться с нашей новой документацией:

Процесс добавления SwaggerUI совершенно аналогичен. Импортируйте SpectacularSwaggerView в верхней части файла, а затем добавьте путь URL для него по адресу api/schema/swagger-ui/:

from django.urls import path, re_path
from .views import PostList, PostDetail, UserPostList
from drf_spectacular.views import SpectacularAPIView, SpectacularRedocView, SpectacularSwaggerView  # 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"),
    path("schema/redoc/", SpectacularRedocView.as_view(url_name="schema"), name="redoc"),
    path("schema/swagger-ui/", SpectacularSwaggerView.as_view(url_name="schema"), name="swagger-ui")  # new
]

Затем перейдете по  адресу http://127.0.0.1:8000/api/schema/swagger-ui/в веб-браузере, чтобы посмотреть результат:

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

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