Django-Rest-Framework: документирование параметров представления на основе функции без модели

Итак, у меня есть представление на основе функций в приложении DRF, которое выглядит примерно так:

from rest_framework.decorators import api_view, permission_classes
from rest_framework.response import Response
from rest_framework.permissions import AllowAny
from rest_framework import status

def passcode_generator(callsign: str) -> int:
    return 0 # Placeholder


@api_view(["POST"])
@permission_classes([AllowAny])
def get_passcode(request):
    callsign = request.data.get("callsign", None)
    if callsign is None:
        raise Response(
            {"error": "Missing callsign"}, status=status.HTTP_400_BAD_REQUEST
        )
    return Response({"passcode": passcode_generator(callsign)})

Очевидно, что "callsign" - единственный ожидаемый аргумент, и он является обязательным. И что "passcode" является единственным полем в ответе. Но DRF этого не знает.

Это означает, что страница API DRF с веб-браузером не может показать вкладку HTML-формы, и означает, что генераторы документации не могут должным образом документировать ее:

Swagger-UI showing the API docs without arguments or return value

Итак, вопрос в том, как можно документировать это представление, основанное на функциях?

Спасибо!

Я не уверен, что это можно сделать с помощью ванильного DRF. Лучший генератор схем для Django, поддерживаемый сейчас, насколько я знаю, это drf-spectacular. Поэтому, если вы используете drf-spectacular, вы должны документировать его таким образом:

@extend_schema(
    parameters=[
        OpenApiParameter(name='callsign', description='<description>', 
                         required=True, type=str),
    ],
    description='More descriptive text'
)
def get_passcode(request):
    callsign = request.data.get("callsign", None)
    # ...

Ответ может быть задокументирован таким образом, согласно тестам:

    @extend_schema_view(
        create=extend_schema(description='creation description', responses={
            201: OpenApiResponse(response=int, description='creation with int response.'),
            222: OpenApiResponse(description='creation with no response.'),
            223: None,
            224: int,
        }),
        list=extend_schema(responses=OpenApiResponse(
            response=OpenApiTypes.INT,
            description='a list that actually returns numbers',
            examples=[OpenApiExample('One', 1), OpenApiExample('Two', 2)],
        )),
    )
Вернуться на верх