Руководство по API Django REST framework (21): Схемы

задняя часть Python API Django

Официальная оригинальная ссылка
Эта серия статей адрес github
Пожалуйста, укажите источник

Schemas

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

Установить основной API

Вам нужно установитьcoreapipackage для добавления поддержки схемы в REST framework.

pip install coreapi

Представление внутренней схемы

Платформа REST использует Core API для моделирования информации о схеме в независимом от формата представлении. Эта информация может быть представлена ​​в различных форматах схемы или использована для создания документации по API.

При использовании основного API схема представлена ​​какDocument, который является объектом-контейнером верхнего уровня для информации об API. Доступные API для интерактивного использованияLinkОбъект представляет. Каждая ссылка содержит URL-адрес, метод HTTP и может включатьFieldСписок экземпляров, описывающих любые параметры, которые может принимать конечная точка API.LinkиFieldЭкземпляры также могут содержать описания, позволяющие отображать схему API в пользовательских документах.

Ниже приведен пример описания API с одной конечной точкой поиска:

coreapi.Document(
    title='Flight Search API',
    url='https://api.example.org/',
    content={
        'search': coreapi.Link(
            url='/search/',
            action='get',
            fields=[
                coreapi.Field(
                    name='from',
                    required=True,
                    location='query',
                    description='City name or airport code.'
                ),
                coreapi.Field(
                    name='to',
                    required=True,
                    location='query',
                    description='City name or airport code.'
                ),
                coreapi.Field(
                    name='date',
                    required=True,
                    location='query',
                    description='Flight date in "YYYY-MM-DD" format.'
                )
            ],
            description='Return flight availability and prices.'
        )
    }
)

Выходной формат схемы

Чтобы отобразиться в ответе HTTP, внутреннее представление должно быть преобразовано в фактические байты, используемые в ответе.

Спецификация Core Json Format предназначена для использования с Core API. Тип REST Framework, включающий этот класс рендерера средств массовой информации для обработки, класс рендерера полезноrenderers.CoreJSONRenderer.

Альтернативный формат схемы

Другие форматы схемы, такие как Open API («Swagger»), JSON HyperSchema или API Blueprint, также могут обрабатываться реализацией.DocumentЭкземпляры преобразуются в строковые представления для поддержки пользовательских классов средства визуализации.

Если имеется пакет кодека Core API, который поддерживает форматирование кодировки в формат, который вы хотите использовать, вы можете использовать этот кодек для реализации класса рендерера.

взять каштан

Например,openapi_codecПакет обеспечивает поддержку кодирования или декодирования для формата Open API («SWARGER»):

from rest_framework import renderers
from openapi_codec import OpenAPICodec

class SwaggerRenderer(renderers.BaseRenderer):
    media_type = 'application/openapi+json'
    format = 'swagger'

    def render(self, data, media_type=None, renderer_context=None):
        codec = OpenAPICodec()
        return codec.dump(data)

Схемы против гипермедиа

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

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

Используя гипермедиа, клиенты видят документы, содержащие данные и доступные взаимодействия. Каждое взаимодействие создает новый документ с подробным описанием текущего состояния и доступных взаимодействий.

создать схему

Платформа REST включает в себя функции для автоматического создания схем или позволяет указать их явно.

Ручная спецификация схемы

Чтобы указать схему вручную, создайте Core API.Document, как в примере выше.

schema = coreapi.Document(
    title='Flight Search API',
    content={
        ...
    }
)

Автоматическая генерация схемы

Автоматическое создание схемыSchemaGeneratorкласс обеспечивает.

SchemaGeneratorОбработайте список шаблонов URL-адресов маршрутов и скомпилируйте надлежащим образом структурированную документацию Core API.

Основное использование просто для предоставления заголовка для схемы и вызоваget_schema():

generator = schemas.SchemaGenerator(title='Flight Search API')
schema = generator.get_schema()

Настроить по схеме представления

По умолчанию просмотр самоанализа доступенAPIViewВверхschemaдоступ к собственностиAutoSchemaэкземпляр выполнен. Это обеспечивает соответствующий Core API для представлений, методов запросов и путей.LinkОбъект:

auto_schema = view.schema
coreapi_link = auto_schema.get_link(...)

(В режиме компиляцииSchemaGeneratorДля каждого представления разрешены вызовы методов и путейview.schema.get_link(). )

Уведомление: для основногоAPIViewПодклассы, внутренняя провинция по умолчанию по существу ограничена параметрами пути URL Kwarg. Для просмотров всех классовGenericAPIViewПодкласс,AutoSchemaПопытаюсь проанализировать поля сериализатора, разбивки на страницы и фильтра и предоставить более подробное описание поля пути. (ключевой крючок здесь актуаленGenericAPIViewСвойства и методы:get_serializer,pagination_class,filter_backendsЖдать. )

чтобы настроитьLinkдля генерации вы можете:

1) использоватьmanual_fieldsсоздать экземпляр kwarg на ваш взглядAutoSchema:

from rest_framework.views import APIView
from rest_framework.schemas import AutoSchema

class CustomView(APIView):
    ...
    schema = AutoSchema(
        manual_fields=[
            coreapi.Field("extra_field", ...),
        ]
    )

Это позволяет расширить наиболее распространенные случаи без создания подклассов.

2) Обеспечивает более сложную настройкуAutoSchemaПодкласс:

from rest_framework.views import APIView
from rest_framework.schemas import AutoSchema

class CustomSchema(AutoSchema):
    def get_link(...):
        # Implement custom introspection here (or in other sub-methods)

class CustomView(APIView):
    ...
    schema = CustomSchema()

Это обеспечивает полный контроль над просмотром самоанализа.

3) создать экземпляр на ваш взглядManualSchema, который явно предоставляет Core API для представленияFields:

from rest_framework.views import APIView
from rest_framework.schemas import ManualSchema

class CustomView(APIView):
    ...
    schema = ManualSchema(fields=[
        coreapi.Field(
            "first_field",
            required=True,
            location="path",
            schema=coreschema.String()
        ),
        coreapi.Field(
            "second_field",
            required=True,
            location="path",
            schema=coreschema.String()
        ),
    ])

Это позволяет задавать схему для некоторых представлений вручную, оставаясь при этом автоматически созданной в других местах.

поставивschemaУстановить какNoneВы можете отключить генерацию SCHEMA представления:

    class CustomView(APIView):
        ...
        schema = None  # Will not appear in schema

Добавить представление схемы

Есть несколько разных способов добавить представление схемы в ваш API, в зависимости от того, что вам нужно.

ярлык get_schema_view

Самый простой способ включить схему в ваш проект — использоватьget_schema_view()функция.

from rest_framework.schemas import get_schema_view

schema_view = get_schema_view(title="Server Monitoring API")

urlpatterns = [
    url('^$', schema_view),
    ...
]

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

$ http http://127.0.0.1:8000/ Accept:application/coreapi+json
HTTP/1.0 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/vnd.coreapi+json

{
    "_meta": {
        "title": "Server Monitoring API"
    },
    "_type": "document",
    ...
}

get_schema_view()Параметры:

title

Может использоваться для предоставления описательного заголовка для определения схемы.

url

Может использоваться для передачи канонического URL-адреса для схемы.

schema_view = get_schema_view(
    title='Server Monitoring API',
    url='https://www.example.org/api/'
)

urlconf

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

schema_view = get_schema_view(
    title='Server Monitoring API',
    url='https://www.example.org/api/',
    urlconf='myproject.urls'
)

renderer_classes

Он используется для доставки конечных точек класса средства рендеринга списка, отображающих корень API.

from rest_framework.schemas import get_schema_view
from rest_framework.renderers import CoreJSONRenderer
from my_custom_package import APIBlueprintRenderer

schema_view = get_schema_view(
    title='Server Monitoring API',
    url='https://www.example.org/api/',
    renderer_classes=[CoreJSONRenderer, APIBlueprintRenderer]
)

patterns

Схема определяется как список самоанализа шаблонов URL. Если вы только хотитеmyproject.apiURL-адрес отображается в схеме:

schema_url_patterns = [
    url(r'^api/', include('myproject.api.urls')),
]

schema_view = get_schema_view(
    title='Server Monitoring API',
    url='https://www.example.org/api/',
    patterns=schema_url_patterns,
)

generator_class

может использоваться для указания перехода кSchemaViewизSchemaGeneratorПодкласс.

authentication_classes

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

permission_classes

Может использоваться для указания списка классов разрешений, которые будут применены к конечной точке схемы. По умолчаниюsettings.DEFAULT_PERMISSION_CLASSES

Используйте явную вид схемы

Если вам нужно больше, чемget_schema_view()Ярлыки для большего контроля, чем вы можете использовать напрямуюSchemaGeneratorкласс для автоматической генерацииDocumentэкземпляр и вернуть этот экземпляр из представления.

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

Используется следующееSchemaGeneratorПример возврата схемы с представлением.

views.py:

from rest_framework.decorators import api_view, renderer_classes
from rest_framework import renderers, response, schemas

generator = schemas.SchemaGenerator(title='Bookings API')

@api_view()
@renderer_classes([renderers.CoreJSONRenderer])
def schema_view(request):
    schema = generator.get_schema(request)
    return response.Response(schema)

urls.py:

urlpatterns = [
    url('/', schema_view),
    ...
]

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

Чтобы представить схему с конечными точками, отфильтрованными по разрешениям пользователя, необходимо добавитьrequestпараметр, переданныйget_schema()метод следующим образом:

@api_view()
@renderer_classes([renderers.CoreJSONRenderer])
def schema_view(request):
    generator = schemas.SchemaGenerator(title='Bookings API')
    return response.Response(generator.get_schema(request=request))

Явное определение схемы

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

import coreapi
from rest_framework.decorators import api_view, renderer_classes
from rest_framework import renderers, response

schema = coreapi.Document(
    title='Bookings API',
    content={
        ...
    }
)

@api_view()
@renderer_classes([renderers.CoreJSONRenderer])
def schema_view(request):
    return response.Response(schema)

файл статической схемы

Последний вариант — записать схему API в виде статического файла, используя один из доступных форматов, таких как Core JSON или Open API.

Тогда ты можешь:

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

Схемы как документы

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

Генерация схемы в среде REST использует Docstrings для автоматического заполнения описаний в документах схемы.

Эти описания будут основаны на:

  • Строка документации соответствующего метода, если он существует.
  • Именованный раздел в строке документации класса, который может состоять из одной или нескольких строк.
  • Строка документации класса.

взять каштан

ОдинAPIView, с явной строкой документации метода.

class ListUsernames(APIView):
    def get(self, request):
        """
        Return a list of all user names in the system.
        """
        usernames = [user.username for user in User.objects.all()]
        return Response(usernames)

ОдинViewSet, с явной строкой документации действия.

class ListUsernames(ViewSet):
    def list(self, request):
        """
        Return a list of all user names in the system.
        """
        usernames = [user.username for user in User.objects.all()]
        return Response(usernames)

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

class UserList(generics.ListCreateAPIView):
    """
    get: List all the users.
    post: Create a new user.
    """
    queryset = User.objects.all()
    serializer_class = UserSerializer
    permission_classes = (IsAdminUser,)

Общий набор представлений с действиями в строках документации класса с использованием многострочных стилей.

class UserViewSet(viewsets.ModelViewSet):
    """
    API endpoint that allows users to be viewed or edited.

    retrieve:
    Return a user instance.

    list:
    Return all users, ordered by most recently joined.
    """
    queryset = User.objects.all().order_by('-date_joined')
    serializer_class = UserSerializer

Справочник по API

SchemaGenerator

Класс, который просматривает список маршрутизируемых шаблонов URL-адресов, запрашивает схему для каждого представления и упорядочивает сгенерированную документацию CoreAPI.

Обычно вы будете использовать параметр, созданныйSchemaGenerator,Следующее:

generator = SchemaGenerator(title='Stock Prices API')

параметр:

  • title обязательный- Имя API.
  • url- Корневой URL-адрес схемы API. Этот параметр не требуется, если схема не включена в префикс пути.
  • patterns- Список URL-адресов для проверки при создании схемы. По умолчанию используется URL-адрес проекта conf.
  • urlconf- Имя модуля конфигурации URL для использования при создании схемы. По умолчаниюsettings.ROOT_URLCONF.

get_schema(self, request)

Возвращает представление схемы APIcoreapi.Documentпример.

@api_view
@renderer_classes([renderers.CoreJSONRenderer])
def schema_view(request):
    generator = schemas.SchemaGenerator(title='Bookings API')
    return Response(generator.get_schema())

requestПараметр не является обязательным и может использоваться, если вы хотите применить разрешения на пользователя для сгенерированной схемы.

get_links(self, request)

Возвращает вложенный словарь, содержащий все ссылки в схеме API.

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

AutoSchema

Класс, который обрабатывает самоанализ отдельных взглядов, генерируемых схемой.

AutoSchemaпройти черезschemaатрибут, прикрепленный кAPIView.

AutoSchemaКонструктор принимает один аргумент ключевого словаmanual_fields.

manual_fields: добавить в созданное полеcoreapi.Fieldпримерlist. Сгенерированные поля с совпадающими именами будут перезаписаны.

class CustomView(APIView):
    schema = AutoSchema(manual_fields=[
        coreapi.Field(
            "my_extra_field",
            required=True,
            location="path",
            schema=coreschema.String()
        ),
    ])

для наследованияAutoSchemaдля настройки генерации схемы.

class CustomViewSchema(AutoSchema):
    """
    Overrides `get_link()` to provide Custom Behavior X
    """

    def get_link(self, path, method, base_url):
        link = super().get_link(path, method, base_url)
        # Do something to customize link here...
        return link

class MyView(APIView):
  schema = CustomViewSchema()

Следующие методы могут быть переопределены.

get_link(self, path, method, base_url)

Возвращает соответствующее представление для данного представленияcoreapi.Linkпример.

Это основная точка входа. Вы можете переопределить это, если вам нужно обеспечить настраиваемое поведение для определенного представления.

get_description(self, path, method)

Возвращает строку, используемую в качестве описания ссылки. По умолчанию это основано на просмотре строки документации, описанной в действии «Схемы как документы» выше.

get_encoding(self, path, method)

Возвращает строку, указывающую кодировку любого тела запроса при взаимодействии с данным представлением. Например'application/json'. Пустая строка может быть возвращена для представлений, не требующих тела запроса.

get_path_fields(self, path, method):

возвращениеcoreapi.Link()Список экземпляров. Используется для каждого параметра пути в URL-адресе.

get_serializer_fields(self, path, method)

возвращениеcoreapi.Link()Список экземпляров. Для каждого поля в классе сериализации, используемом представлением.

get_pagination_fields(self, path, method)

возвращениеcoreapi.Link()Список экземпляров, список состоит изget_schema_fields()Метод возвращает класс разбиения на страницы, используемый представлением.

get_filter_fields(self, path, method)

возвращениеcoreapi.Link()список экземпляров класса фильтра, используемого представлениемget_schema_fields()метод возвращен.

get_manual_fields(self, path, method)

возвращениеcoreapi.Field()Список экземпляров для добавления или замены сгенерированных полей. По умолчанию (необязательно) передается наAutoSchemaТекстурная функцияmanual_fields.

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

def get_manual_fields(self, path, method):
    """Example adding per-method fields."""

    extra_fields = []
    if method=='GET':
        extra_fields = # ... list of extra fields for GET ...
    if method=='POST':
        extra_fields = # ... list of extra fields for POST ...

    manual_fields = super().get_manual_fields(path, method)
    return manual_fields + extra_fields

update_fields(fields, update_with)

Полезныйstaticmethod. инкапсулировать логику для передачиField.nameДобавьте или замените поля в списке. Может быть переопределен для корректировки критериев замены.

ManualSchema

Позволяет указать схему вручнуюcoreapi.FieldСписок экземпляров и необязательное описание.

class MyView(APIView):
  schema = ManualSchema(fields=[
        coreapi.Field(
            "first_field",
            required=True,
            location="path",
            schema=coreschema.String()
        ),
        coreapi.Field(
            "second_field",
            required=True,
            location="path",
            schema=coreschema.String()
        ),
    ]
  )

ManualSchemaКонструктор имеет два параметра:

fields: coreapi.FieldСписок экземпляров. Необходимые.

description: Строковое описание. по желанию.

Core API

В этом документе кратко описывается схема, используемая для представления схемы API.coreapiкомпоненты в упаковке.

Обратите внимание, что эти классы являются производными отcoreapiпосылка импортирована, а не изrest_frameworkпакет импортный.

Document

Контейнер, представляющий схему API.

title

Имя API.

url

Канонический URL для API.

content

словарь, содержащий схемыLinkобъект.

Для того, чтобы обеспечить больше структуры к схеме,contentСловари могут быть вложенными, обычно двухуровневыми. Например:

content={
    "bookings": {
        "list": Link(...),
        "create": Link(...),
        ...
    },
    "venues": {
        "list": Link(...),
        ...
    },
    ...
}

Link

Он представляет собой одну конечную точку API.

url

URL-адрес конечной точки. Может быть шаблон URI, такой как/users/{username}/.

action

Метод HTTP, связанный с конечной точкой. Обратите внимание, что URL-адреса, поддерживающие несколько методов HTTP, должны соответствовать одной ссылке для каждого метода HTTP.

fields

FieldСписок экземпляров, описывающих параметры, доступные на входе.

description

Краткое описание значения и назначения конечной точки.

Field

Представляет один входной параметр в заданной конечной точке API.

name

Введите описательное имя.

required

Логическое значение, указывающее, должен ли клиент включать значение или параметр можно опустить.

location

Определяет, как кодировать информацию в запросе. Должна быть одна из следующих строк:

"path"

Включен в шаблонный URI. Например,/products/{product_code}/изurlзначение можно сравнить с"path"Поле используется вместе для обработки пути ввода URL API, например,/products/slim-fit-jeans/.

Эти поля обычно соответствуют именованным параметрам в конфигурации URL-адреса проекта.

"query"

Включены в качестве параметров запроса URL. Например?search=sale. обычно используется дляGETпросить.

Эти поля обычно соответствуют элементам управления разбиением по страницам и фильтрации в представлении.

"form"

Включается в тело запроса как объект JSON или отдельный элемент HTML-формы. Например{"colour": "blue", ...}. обычно используется дляPOST,PUTиPATCHпросить. несколько"form"Поля могут быть включены в одну ссылку.

Эти поля обычно соответствуют полям сериализованного класса в представлении.

"body"

Содержит полное тело запроса. обычно используется дляPOST, PUTиPATCHпросить. Там должно быть не более одной ссылки на"body"поле. не может быть с"form"поля используются вместе.

Эти поля обычно соответствуют использованиюListSerializerдля проверки ввода запроса или использования представления загрузки файла.

encoding

"application/json"

Содержимое запроса в формате JSON. соответствует использованиюJSONParserПосмотреть. только приLinkсодержит один или несколькоlocation="form"полевой или одиночныйlocation="body"поле допустимо.

"multipart/form-data"

Содержимое закодированного запроса, состоящего из нескольких частей. соответствует использованиюMultiPartParserПосмотреть. только приLinkсодержит один или несколькоlocation="form"поле допустимо.

"application/x-www-form-urlencoded"

URL закодированный контент запроса. соответствует использованиюFormParserПосмотреть. только приLinkсодержит один или несколькоlocation="form"поле допустимо.

"application/octet-stream"

Содержимое запроса на двоичную загрузку. соответствует использованиюFileUploadParserПосмотреть. только приLinkсодержитlocation="body"поле допустимо.

description

Краткое описание значения и назначения поля ввода.

Категории