Django позволяет легко быстро раскрутить API и предоставляет отличный интерфейс администратора и инструменты управления командными строками. Это, безусловно, ускоряет развитие любой системы CRUD.
Однако, поскольку ваш проект растет, вы захотите убедиться, что ваш код будет хорошо документирован как для ваших Backend Developers, так и для внутренних клиентов, которые потребляют ваш API.
В этом Post Blog я буду набросать, как использовать Python 3.7 Dataclasses для записи аннотированного и документированного кода и OperAPI (SWAGER), чтобы автоматически документировать вашу API.
О Dataclasses.
Dataclass Декоратор, добавленный в Python 3.7 обеспечивает некоторые преимущества при использовании в классах:
- Создает классы, которые обеспечивают автоматическое
__init __ ()и__REPR () __методы - Позволяет указывать атрибуты класса и их типы с использованием синтаксиса аннотации типа
- Атрибуты и их типы являются обнаружены программно, что позволяет другим модулям использовать их как более чем просто синтаксический синтаксис, например, для проверки.
В этом посте в блоге я покажу, как Dataclasses можно использовать для Django Rest Framework Serializers, используя djangorestframework-dataclasses. . Это позволяет определять классы для использования в вашем приложении, а также иметь их сериализацию для ввода и вывода Django.
О openapi.
Openapi (или Swagger) позволяет документировать вашу API с помощью JSON. Он также предоставляет интерфейс, в котором люди, потребляющие ваши API, могут видеть документацию API и попробуйте звонить на лету.
Установка поддержки OpenAPI для DRF
Для opener renderer, Pyyaml и мочеиспускание Требуются для генерации документации API YAML:
pip install pyyaml uritemplate
После установки зависимостей вы можете автоматически генерировать вашу документацию SWARGER, включая два маршрута.
Во-первых, для генерации YAML, который будет использоваться Openapi, звоните get_schema_view Чтобы получить вид DRF для использования в вашем URLS.PY :
from rest_framework.schemas import get_schema_view
urlpatterns += [
url(r'^openapi-schema', get_schema_view(
title="Tutorial app", # Title of your app
description="tutorial app", # Description of your app
version="1.0.0",
public=True,
), name='openapi-schema'),
]Это вызовут схему YAML в маршруте/Open-API. Схема будет автоматически обновляться с ваших маршрутов и сериализаторов и перечисляет все URL-адреса и их входы и выходы.
Используйте следующий запрос, чтобы проверить это:
curl -HContent-Type:application/json http://localhost:8000/openapi-schema/ # mind the content-type
# Response:
openapi: 3.0.2
info:
title: Tutorial app
version: 1.0.0
description: tutorial app
paths:
/hello/hello/:
get:
operationId: helloPerson
description: ''
parameters: []
responses:
'200':
content:
application/json:
schema:
properties:
name:
type: string
age:
type: integer
required:
- name
- age
description: ''
Как только схема схемы вы можете добавить Swagger UI на ваш API.
Чтобы сделать это, вы можете настроить статическую HTML-страницу и загрузить сценарии из CDN, затем визуализируйте его как шаблон.
HTML-страница, скопированная из Документация DRF , составляет:
Swagger
SwAgwuiBundle автоматически генерирует ваш интерфейс UI, вам не нужно ничего делать. Единственным интересным значением здесь является Schema_URL, который должен указывать на вашу схему URL, определенного выше.
Затем вы можете загрузить этот шаблон, добавив следующее на свои URLPatterns:
url(r'docs/', TemplateView.as_view(
template_name='swagger-ui.html',
extra_context={'schema_url': 'openapi-schema'}
), name='swagger-ui'),
Загрузить /Документы/ Маршрут в вашем браузере. Если все было настроено правильно, вы должны увидеть UI Swagger.
UI Swagger позволяет вам увидеть все маршруты и параметры вашего API, и даже попробуйте API звонки на лету!
Установка сериализатора Dataclass для DRF
Как упоминалось ранее, сериализатор Dataclass позволяет преобразовать Python Dataclasses на JSON и VICE-VERSIA, предлагая проверку пользовательских данных.
Рассмотрим следующую таблицу Dataclass:
@dataclass class Person(): name: str age: int
Ваши пользователи могут отправлять данные JSON с именем и возрастами свойствами, а djangorestframework-dataclass будет подтверждать данные и десериализировать в Человек Объект, который вы можете напрямую использовать в ваших методах домена.
Чтобы установить модуль:
pip install djangorestframework-dataclasses
После установки все, что вам нужно сделать, чтобы написать свой сериализатор, это наследовать от Dataclassserializer и установить Dataclass Мета имущество.
class PersonSerializer(DataclassSerializer):
class Meta:
dataclass = Person
Теперь вы можете использовать Лицериализатор в вашем API как обычно.
from django.http import JsonResponse
from rest_framework.decorators import action
from rest_framework.viewsets import GenericViewSet
from tutorial.serializers import Person, PersonSerializer
class PersonViewSet(GenericViewSet):
serializer_class = PersonSerializer
@action(detail=False, methods=['post'])
def get_age(self, request):
person_serializer = PersonSerializer(data=request.data)
if (not person_serializer.is_valid()):
return JsonResponse(person_serializer.errors)
person: Person = person_serializer.validated_data # will return a Person object
return JsonResponse({'age': person.age})
person_serializer.validated_data вернет объект Человек класс. Это позволяет использовать ваши Dataclasses, как вы хотите во время вашего приложения.
Более того, документация SWARGER, которую мы реализовали ранее, позволяет видеть формат ввода и вывода для объектов вашего человека, предоставляемых вашими сериализаторами.
Нажмите «Попробуйте», чтобы отправить объект человека с любыми значениями:
После отправки данных вы можете увидеть ответ сервера, позволяя вам легко проверить и отладки вашего API.
Вывод
В заключение SWARGER UI является мощным инструментом документации, который может автоматически генерировать документацию для любых API Django-Rest-Framework. Вы можете использовать его с любым типом DRF Serializer (например, Modelerializer), но если вы хотите использовать Dataclasses и типы для документации, Dataclass-serializer дает вам дополнительное преимущество: ваш код документирован не только для ваших потребителей, но и для ваших разработчиков
Оригинал: “https://dev.to/errietta/documenting-a-django-api-with-openapi-and-dataclasses-1p6h”