Документирование конечной точки DRF GET с несколькими ответами с использованием Swagger - PullRequest
Новая
       73

Документирование конечной точки DRF GET с несколькими ответами с использованием Swagger

2 голосов
/ 20 апреля 2019

У меня есть конечная точка GET для RESTful API, который я создаю с использованием Django. Эта конечная точка считывает три значения из строки запроса URL. Определенный параметр в строке запроса может изменить данные (включить дополнительные поля и слегка изменить структуру), которые возвращаются в ответе JSON от этой конечной точки.

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

Моя проблема заключается в следующем:

Я бы хотел документировать эту конечную точку, используя Swagger. Я использую drf-yasg для генерации документации по Swagger. У меня нет сериализаторов, заявленных для этого представления; так как я вручную создаю упорядоченный словарь в get_object, я не вижу цели объявить его. Я не уверен, как документировать мою конечную точку, используя drf-yasg.

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

Объявляя объект openapi.Response и передавая этот объект декоратору @swagger_auto_schema, Swagger отображает два возможных ответа, но описание всего ответа действительно раздувает мой код. Вот пример того, что в настоящее время работает для документирования конечной точки: 

class View(RetrieveAPIView):

    http_method_names = ['get']

    response_json = {
        'Response if X query parameter is something': {
            'key1': 'string',
            'key3': {
                'key4': 0,
                'key5': 'string',
                'key6': 'string'
            }
        },
        'Response if X query parameter is something else': {
            'key1': 'string',
            'key2': 'string'
        }
    }
    swagger_get_responses = openapi.Response(description='Description for the set of responses',
                                             examples=response_json)

    @swagger_auto_schema(responses={200: swagger_get_responses})
    def get(self, request, *args, **kwargs):
        return super().get(request, args, kwargs)

    def get_object(self):
        // Execute a method on a model that queries other models, performs some logic, and 
        // then returns an ordered dict which is then returned by this function.

Есть ли лучший подход к этой проблеме? Есть ли лучший шаблон / функция дизайна Django инфраструктуры Django или библиотеки drf-yasg, которую я могу применить здесь, которая поможет мне обрабатывать несколько тел ответов?

...