Django REST Framework
  • Overview
    • Django REST framework
    • Быстрый старт
      • Сериализация
      • Запросы-ответы
      • Представления-классы
      • Аутентификация/права доступа
      • Отношения и связи
      • Наборы представлений и роутеры
    • Навигация по API:
      • Запросы
      • Ответы
      • Представления
      • Общие представления
      • Viewsets
      • Маршрутизаторы
      • Парсеры
      • Рендереры
      • Сериализаторы
      • Поля сериализатора
      • Отношения сериализаторов
      • Валидаторы
      • Аутентификация
      • Разрешения
      • Кэширование
      • Дросселирование
      • Фильтрация
      • Пагинация
      • Версионирование
      • Согласование контента
      • Метаданные
      • Schemas
      • Cуффиксы формата
      • Возвращение URL-адресов
      • Исключения
      • Коды состояния
      • Тестирование
      • Настройки
  • Статьи
    • Статьи
      • AJAX, CSRF & CORS
      • The Browsable API
      • Улучшения в браузере
      • Документирование вашего API
      • HTML и формы
      • Интернационализация
      • REST, гипермедиа и HATEOAS
      • Вложенные сериализаторы с возможностью записи
Powered by GitBook
On this page
  • Пакеты сторонних разработчиков для поддержки OpenAPI
  • drf-spectacular
  • drf-yasg
  • Built-in OpenAPI schema generation (deprecated)
  • Встроенная генерация схем OpenAPI (устаревшая)
  • Минимальный пример с Swagger UI
  • Минимальный пример с ReDoc.
  • Самоописывающиеся API
  • The hypermedia approach
  • Гипермедийный подход

Was this helpful?

  1. Статьи
  2. Статьи

Документирование вашего API

PreviousУлучшения в браузереNextHTML и формы

Last updated 1 year ago

Was this helpful?

REST API должен тратить почти все свои усилия по описанию на определение типа(ов) носителей, используемых для представления ресурсов и управления состоянием приложения.

  • Рой Филдинг,

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

Пакеты сторонних разработчиков для поддержки OpenAPI

drf-spectacular

- это библиотека генерации схем с явным акцентом на расширяемость, настраиваемость и генерацию клиентов. Это рекомендуемый способ генерации и представления схем OpenAPI.

Библиотека стремится извлечь как можно больше информации о схеме, предоставляя при этом декораторы и расширения для легкой настройки. Имеется явная поддержка , и , i18n, версионность, аутентификация, полиморфизм (динамические запросы и ответы), параметры запроса/пути/заголовка, документация и многое другое. Несколько популярных плагинов для DRF также поддерживаются "из коробки".

drf-yasg

- это инструмент генерации , реализованный без использования генерации схем, предоставляемой DRF.

Его цель - реализовать как можно больше спецификации - вложенные схемы, именованные модели, тела ответов, валидаторы enum/pattern/min/max, параметры формы и др. - и генерировать документы, пригодные для использования с помощью инструментов генерации кода, таких как swagger-codegen.

Это также воплощается в очень полезном интерактивном средстве просмотра документации в виде swagger-ui:

Скриншот - drf-yasg

Built-in OpenAPI schema generation (deprecated)

Встроенная генерация схем OpenAPI (устаревшая)

Существует ряд пакетов, позволяющих генерировать HTML-страницы документации на основе схем OpenAPI.

Оба требуют лишь указания местоположения статического файла схемы или динамической конечной точки SchemaView.

Минимальный пример с Swagger UI

Если предположить, что вы последовали примеру из документации по схемам для маршрутизации динамического 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: "<div data-gb-custom-block data-tag="url"></div>",
        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>

Сохраните его в папке templates под именем 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",
    ),
]

Минимальный пример с 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="<div data-gb-custom-block data-tag="url"></div>"></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",
    ),
]

Самоописывающиеся API

Web-интерфейс API, который предоставляет DRF, позволяет вашему API быть полностью самоописывающимся. Документация для каждой конечной точки API может быть предоставлена просто при посещении URL-адреса в браузере.


Установка заголовка

Заголовок, который используется в Web-интерфейсе API, генерируется из имени класса представления или имени функции. Любой суффикс View или ViewSet удаляется, а строка разделяется пробелами по прописным/строчным буквам или подчеркиваниям.

Например, представление UserListView, будет называться User List, когда будет представлено в Web-интерфейсе API.

При работе с наборами представлений к каждому сгенерированному представлению добавляется соответствующий суффикс. Например, набор представлений UserViewSet будет генерировать представления с именами User List и User Instance.

Установка описания

Описание в Web-интерфейсе API генерируется из docstring представления или набора представлений.

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
    """

Метод OPTIONS.

API DRF также поддерживают программно доступные описания, используя HTTP-метод OPTIONS. Представление отвечает на запрос OPTIONS с метаданными, включающими название, описание и различные типы медиа, которые оно принимает и на которые отвечает.

При использовании общих представлений, любые запросы OPTIONS будут получать ответ с метаданными о любых доступных действиях POST или PUT, описывая, какие поля находятся в сериализаторе.

Вы можете изменить поведение ответа на OPTIONS запросы, переопределив метод представления options и/или предоставив пользовательский класс Metadata. Например:

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 hypermedia approach

Гипермедийный подход

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

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

Уведомление о сокращении: Встроенная в REST framework поддержка генерации схем OpenAPI устарела в пользу сторонних пакетов, которые могут предоставить эту функциональность вместо нее. В качестве замены мы рекомендуем использовать пакет ..

Два популярных варианта - и .

Расширенные возможности использования см. в .

Расширенное использование см. в .

Скриншот - API самоописания

Если установлена библиотека python Markdown, то в docstring можно использовать , который будет преобразован в HTML в Web-интерфейсе API. Например:

Обратите внимание, что при использовании наборов представлений базовая строка документа используется для всех создаваемых представлений. Чтобы предоставить описания для каждого представления, например, для представлений list и retrieve, используйте секции docstring, как описано в .

Более подробную информацию смотрите в .

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

Swagger UI
ReDoc
Swagger UI documentation
документации ReDoc
синтаксис markdown
Schemas as documentation
документации по метаданным
REST, Hypermedia & HATEOAS
drf-spectacular
REST API должны быть гипертекстовыми
drf-spectacular
OpenAPI 3
swagger-codegen
SwaggerUI
Redoc
drf-yasg
Swagger / OpenAPI 2
OpenAPI 2