Документирование вашего API¶
REST API должен потратить почти все свои усилия по описанию на определение типа(ов) носителей, используемых для представления ресурсов и управления состоянием приложения.
‒ Рой Филдинг, <<<0>>.
REST framework предоставляет встроенную поддержку для генерации схем OpenAPI, которые можно использовать с инструментами, позволяющими создавать документацию API.
Также существует множество отличных пакетов документации от сторонних разработчиков.
Генерация документации из схем OpenAPI¶
Существует ряд пакетов, позволяющих генерировать HTML-страницы документации на основе схем OpenAPI.
Два популярных варианта - Swagger UI и ReDoc.
Оба варианта требуют лишь указания местоположения статического файла схемы или динамической конечной точки SchemaView.
Минимальный пример с пользовательским интерфейсом Swagger¶
Если предположить, что вы последовали примеру из документации по схемам для маршрутизации динамического SchemaView, минимальный шаблон Django для использования Swagger UI может быть таким:
<!DOCTYPE html>
<html>
<head>
<title>Swagger</title>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" type="text/css" href="//unpkg.com/swagger-ui-dist@3/swagger-ui.css" />
</head>
<body>
<div id="swagger-ui"></div>
<script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
<script>
const ui = SwaggerUIBundle({
url: "{% url schema_url %}",
dom_id: '#swagger-ui',
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIBundle.SwaggerUIStandalonePreset
],
layout: "BaseLayout",
requestInterceptor: (request) => {
request.headers['X-CSRFToken'] = "{{ csrf_token }}"
return request;
}
})
</script>
</body>
</html>
Сохраните это в папке с шаблонами как swagger-ui.html. Затем проложите маршрут TemplateView в URL conf вашего проекта:
from django.views.generic import TemplateView
urlpatterns = [
# ...
# Route TemplateView to serve Swagger UI template.
# * Provide `extra_context` with view name of `SchemaView`.
path('swagger-ui/', TemplateView.as_view(
template_name='swagger-ui.html',
extra_context={'schema_url':'openapi-schema'}
), name='swagger-ui'),
]
См. Swagger UI documentation для расширенного использования.
Минимальный пример с ReDoc.¶
Предполагая, что вы последовали примеру из документации по схемам для маршрутизации динамического SchemaView , минимальный шаблон Django для использования ReDoc может быть следующим:
<!DOCTYPE html>
<html>
<head>
<title>ReDoc</title>
<!-- needed for adaptive design -->
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
<!-- ReDoc doesn't change outer page styles -->
<style>
body {
margin: 0;
padding: 0;
}
</style>
</head>
<body>
<redoc spec-url='{% url schema_url %}'></redoc>
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
</body>
</html>
Сохраните это в папке с шаблонами как redoc.html. Затем проложите маршрут TemplateView в URL conf вашего проекта:
from django.views.generic import TemplateView
urlpatterns = [
# ...
# Route TemplateView to serve the ReDoc template.
# * Provide `extra_context` with view name of `SchemaView`.
path('redoc/', TemplateView.as_view(
template_name='redoc.html',
extra_context={'schema_url':'openapi-schema'}
), name='redoc'),
]
См. ReDoc documentation для расширенного использования.
Пакеты сторонних производителей¶
Существует ряд готовых пакетов сторонних разработчиков для предоставления документации по API.
drf-yasg - это инструмент генерации Swagger, реализованный без использования генерации схемы, предоставляемой Django Rest Framework.
Его цель - реализовать как можно больше спецификации OpenAPI - вложенные схемы, именованные модели, тела ответов, валидаторы enum/pattern/min/max, параметры формы и др. - и генерировать документы, пригодные для использования с инструментами генерации кода, такими как swagger-codegen.
Это также воплощается в очень полезный интерактивный просмотрщик документации в виде swagger-ui :
drf-spectacular - это инструмент генерации схем OpenAPI 3 с явным акцентом на расширяемость, настраиваемость и генерацию клиентов. Модели использования очень похожи на drf-yasg.
Его цель - извлечь как можно больше информации о схеме, при этом предоставляя декораторы и расширения для легкой настройки. Имеется явная поддержка swagger-codegen и :doc:`Redoc <https://github.com/Rebilly/ReDoc>`** , i18n, версионность, аутентификация, полиморфизм (динамические запросы и ответы), параметры запроса/пути/заголовка, документация и многое другое. Несколько популярных плагинов для DRF также поддерживаются «из коробки».
Самоописывающиеся API¶
Просматриваемый API, который предоставляет фреймворк REST, позволяет вашему API быть полностью самоописывающимся. Документация для каждой конечной точки API может быть предоставлена просто при посещении URL-адреса в браузере.
Заголовок, используемый в просматриваемом API, генерируется из имени класса представления или имени функции. Любой суффикс View или ViewSet удаляется, и строка разделяется пробелами по границам прописных/строчных букв или подчеркиваниями.
Например, представление UserListView , будет названо User List при представлении в просматриваемом API.
При работе с наборами представлений к каждому сгенерированному представлению добавляется соответствующий суффикс. Например, набор представлений UserViewSet будет генерировать представления с именами User List и User Instance.
Описание в просматриваемом API генерируется из docstring представления или набора представлений.
Если установлена библиотека python Markdown, то в docstring можно использовать markdown syntax, которая будет преобразована в HTML в просматриваемом API. Например:
class AccountListView(views.APIView):
"""
Returns a list of all **active** accounts in the system.
For more details on how accounts are activated please [see here][ref].
[ref]: http://example.com/activating-accounts
"""
Обратите внимание, что при использовании наборов представлений базовая строка docstring используется для всех создаваемых представлений. Чтобы предоставить описания для каждого представления, например, для представлений list и retrieve, используйте секции docstring, как описано в Schemas as documentation: Examples.
API фреймворка REST также поддерживают программно доступные описания, используя метод OPTIONS HTTP. Представление отвечает на запрос OPTIONS с метаданными, включающими название, описание и различные типы медиа, которые оно принимает и на которые отвечает.
При использовании общих представлений, любые запросы OPTIONS будут дополнительно отвечать метаданными о любых доступных действиях POST или PUT, описывая, какие поля находятся в сериализаторе.
Вы можете изменить поведение ответа на запросы OPTIONS, переопределив метод представления options и/или предоставив пользовательский класс метаданных. Например:
def options(self, request, *args, **kwargs):
"""
Don't include the view description in OPTIONS responses.
"""
meta = self.metadata_class()
data = meta.determine_metadata(request, self)
data.pop('description')
return Response(data=data, status=status.HTTP_200_OK)
Более подробную информацию см. в разделе the Metadata docs.
Гипермедийный подход¶
Чтобы быть полностью RESTful, API должен представлять свои доступные действия в виде гипермедийных элементов управления в ответах, которые он отправляет.
При таком подходе, вместо того чтобы документировать доступные конечные точки API, описание концентрируется на типах медиа, которые используются. Доступные действия, которые могут быть предприняты на любом данном URL, не являются строго фиксированными, но вместо этого становятся доступными благодаря наличию элементов управления ссылками и формами в возвращаемом документе.
Для реализации гипермедийного API вам необходимо выбрать подходящий тип медиа для API и реализовать пользовательский рендерер и парсер для этого типа медиа. Раздел документации REST, Hypermedia & HATEOAS содержит указатели на справочную литературу, а также ссылки на различные форматы гипермедиа.