Comment générer une liste de messages de réponse dans Django REST Swagger?

J'ai mis à jour Django REST Framework à 3.5.0 hier parce que j'ai besoin de génération de schéma agréable.

j'utilise Django REST Swagger document mon API, mais ne sais pas comment afficher la liste de tous les possibles, les messages de réponse qu'une API endpoint offre.

il semble qu'il y ait une génération automatique de message de succès correspondant à l'action que mon paramètre exécute.

ainsi, postez les actions générant le code de réponse 201, sans aucune Description.

enter image description here

Comment pourrais-je ajouter tous les messages de réponse que mon paramètre fournit et leur donner quelques descriptions?

j'utilise

djangorestframework==3.5.0

django-rest-swagger==2.0.7

20
demandé sur Grokify 2016-10-21 14:23:09

1 réponses

Ah, J'ai enfin compris.

Mais! C'est hack sur hack - et probablement Drf + DRF swagger ne supporte pas cela; fondamentalement le problème n'est pas connecté au code swagger drf et drf, plutôt le codec openapi, voir vous-même:

def _get_responses(link):
    """
    Returns minimally acceptable responses object based
    on action / method type.
    """
    template = {'description': ''}
    if link.action.lower() == 'post':
        return {'201': template}
    if link.action.lower() == 'delete':
        return {'204': template}
    return {'200': template}

Le code ci-dessus peut être trouvé à: openapi_codec/encode.py - github Ce n'est pas lié de quelque manière drf ou drf swagger - pour chaque lien (par exemple.: GET /api/v1/test/) créer un modèle avec une description vide.

De sûr, il y a une possibilité de surmonter ce problème. Mais comme je l'ai dit - c'est hack sur hack :) je vais partager un exemple:

docs_swagger.views.py

from rest_framework import exceptions
from rest_framework.permissions import AllowAny
from rest_framework.renderers import CoreJSONRenderer
from rest_framework.response import Response
from rest_framework.views import APIView
from rest_framework_swagger import renderers

from docs_swagger.schema_generator import CustomSchemaGenerator


def get_swagger_view(title=None, url=None):
    """
    Returns schema view which renders Swagger/OpenAPI.

    (Replace with DRF get_schema_view shortcut in 3.5)
    """
    class SwaggerSchemaView(APIView):
        _ignore_model_permissions = True
        exclude_from_schema = True
        permission_classes = [AllowAny]
        renderer_classes = [
            CoreJSONRenderer,
            renderers.OpenAPIRenderer,
            renderers.SwaggerUIRenderer
        ]

        def get(self, request):
            generator = CustomSchemaGenerator(title=title, url=url)  # this is altered line
            schema = generator.get_schema(request=request)
            if not schema:
                raise exceptions.ValidationError(
                    'The schema generator did not return a schema   Document'
                )
            return Response(schema)

    return SwaggerSchemaView.as_view()

ce que je fais dans le CustomSchemaGenerator est comme suit:

docs_swagger.schema_generator.py

import urlparse
import coreapi
from rest_framework.schemas import SchemaGenerator

from openapi_codec import encode


def _custom_get_responses(link):
    detail = False
    if '{id}' in link.url:
        detail = True
    return link._responses_docs.get(
        '{}_{}'.format(link.action, 'list' if not detail else 'detail'),
        link._responses_docs
    )


# Very nasty; Monkey patching;
encode._get_responses = _custom_get_responses


class CustomSchemaGenerator(SchemaGenerator):

    def get_link(self, path, method, view):
        """
        Return a `coreapi.Link` instance for the given endpoint.
        """
        fields = self.get_path_fields(path, method, view)
        fields += self.get_serializer_fields(path, method, view)
        fields += self.get_pagination_fields(path, method, view)
        fields += self.get_filter_fields(path, method, view)

        if fields and any([field.location in ('form', 'body') for field in fields]):
            encoding = self.get_encoding(path, method, view)
        else:
            encoding = None

        description = self.get_description(path, method, view)

        if self.url and path.startswith('/'):
            path = path[1:]

        # CUSTOM
        data_link = coreapi.Link(
            url=urlparse.urljoin(self.url, path),
            action=method.lower(),
            encoding=encoding,
            fields=fields,
            description=description
        )

        data_link._responses_docs = self.get_response_docs(path, method, view)

        return data_link

    def get_response_docs(self, path, method, view):
        return view.responses_docs if hasattr(view, 'responses_docs') else {'200': {
            'description': 'No response docs definition found.'}
        }

Et enfin:

my_view.py

class TestViewSet(viewsets.ModelViewSet):
    queryset = Test.objects.all()
    serializer_class = TestSerializer

    responses_docs = {
        'get_list': {
            '200': {
                'description': 'Return the list of the Test objects.',
                'schema': {
                    'type': 'array',
                    'items': {
                        'type': 'object',
                        'properties': {
                            'id': {
                                'type': 'integer'
                            }
                        }
                    }
                }
            },
            '404': {
                'description': 'Not found',
                'schema': {
                    'type': 'object',
                    'properties': {
                        'message': {
                            'type': 'string'
                        }
                    }
                },
                'example': {
                    'message': 'Not found.'
                }
            }
        },
        'get_detail': {
            '200': {
                'description': 'Return single Test object.',
                'schema': {
                    'type': 'object',
                    'properties': {
                        'id': {
                            'type': 'integer'
                        }
                    }
                }
            },
            '404': {
                'description': 'Not found.',
                'schema': {
                    'type': 'object',
                    'properties': {
                        'message': {
                            'type': 'string'
                        }
                    }
                },
                'example': {
                    'message': 'Not found.'
                }
            }
        }
    }

je considère cela plus comme amusant au lieu d'une VRAIE solution. La vraie solution est probablement impossible pour atteindre à l'état actuel. Peut - être devriez-vous demander aux créateurs de Drf swagger-ont-ils des plans pour soutenir les réponses?

quoi Qu'il en soit, le Swagger UI: enter image description here

bon codage :)

17
répondu opalczynski 2017-05-30 11:50:48