From f415a96aa62be948165d9ee20206fdfe8227b3e0 Mon Sep 17 00:00:00 2001 From: Vitali Fokin Date: Tue, 11 Dec 2018 21:13:37 +0300 Subject: [PATCH] Tags override support (#259) --- CONTRIBUTING.rst | 2 ++ src/drf_yasg/inspectors/view.py | 9 +++++++-- src/drf_yasg/utils.py | 4 +++- testproj/users/views.py | 15 ++++++++++----- tests/reference.yaml | 10 +++++----- 5 files changed, 27 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index d6c8181..50670e8 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -70,6 +70,8 @@ You want to contribute some code? Great! Here are a few steps to get you started # (optional) sort imports with isort and check flake8 linting (venv) $ isort --apply (venv) $ flake8 src/drf_yasg testproj tests setup.py + # install test dependencies + (venv) $ pip install -U -r requirements/test.txt # run tests in the current environment, faster than tox (venv) $ pytest --cov # (optional) run tests for other python versions in separate environments diff --git a/src/drf_yasg/inspectors/view.py b/src/drf_yasg/inspectors/view.py index 3a83f16..bbbb086 100644 --- a/src/drf_yasg/inspectors/view.py +++ b/src/drf_yasg/inspectors/view.py @@ -376,13 +376,18 @@ class SwaggerAutoSchema(ViewInspector): def get_tags(self, operation_keys): """Get a list of tags for this operation. Tags determine how operations relate with each other, and in the UI - each tag will show as a group containing the operations that use it. + each tag will show as a group containing the operations that use it. If not provided in overrides, + tags will be inferred from the operation url. :param tuple[str] operation_keys: an array of keys derived from the pathdescribing the hierarchical layout of this view in the API; e.g. ``('snippets', 'list')``, ``('snippets', 'retrieve')``, etc. :rtype: list[str] """ - return [operation_keys[0]] + tags = self.overrides.get('tags') + if not tags: + tags = [operation_keys[0]] + + return tags def get_consumes(self): """Return the MIME types this endpoint can consume. diff --git a/src/drf_yasg/utils.py b/src/drf_yasg/utils.py index 55cce59..1682c10 100644 --- a/src/drf_yasg/utils.py +++ b/src/drf_yasg/utils.py @@ -29,7 +29,7 @@ class unset(object): def swagger_auto_schema(method=None, methods=None, auto_schema=unset, request_body=None, query_serializer=None, manual_parameters=None, operation_id=None, operation_description=None, operation_summary=None, security=None, deprecated=None, responses=None, field_inspectors=None, filter_inspectors=None, - paginator_inspectors=None, **extra_overrides): + paginator_inspectors=None, tags=None, **extra_overrides): """Decorate a view method to customize the :class:`.Operation` object generated from it. `method` and `methods` are mutually exclusive and must only be present when decorating a view method that accepts @@ -96,6 +96,7 @@ def swagger_auto_schema(method=None, methods=None, auto_schema=unset, request_bo :attr:`.ViewInspector.filter_inspectors` on the :class:`.inspectors.SwaggerAutoSchema` instance :param list[.PaginatorInspector] paginator_inspectors: extra paginator inspectors; these will be tried before :attr:`.ViewInspector.paginator_inspectors` on the :class:`.inspectors.SwaggerAutoSchema` instance + :param list[str] tags: tags override :param extra_overrides: extra values that will be saved into the ``overrides`` dict; these values will be available in the handling :class:`.inspectors.SwaggerAutoSchema` instance via ``self.overrides`` """ @@ -115,6 +116,7 @@ def swagger_auto_schema(method=None, methods=None, auto_schema=unset, request_bo 'filter_inspectors': list(filter_inspectors) if filter_inspectors else None, 'paginator_inspectors': list(paginator_inspectors) if paginator_inspectors else None, 'field_inspectors': list(field_inspectors) if field_inspectors else None, + 'tags': list(tags) if tags else None, } data = filter_none(data) if auto_schema is not unset: diff --git a/testproj/users/views.py b/testproj/users/views.py index b261ef6..d7251f4 100644 --- a/testproj/users/views.py +++ b/testproj/users/views.py @@ -13,7 +13,11 @@ from users.serializers import UserListQuerySerializer, UserSerializerrr class UserList(APIView): """UserList cbv classdoc""" - @swagger_auto_schema(query_serializer=UserListQuerySerializer, responses={200: UserSerializerrr(many=True)}) + @swagger_auto_schema( + query_serializer=UserListQuerySerializer, + responses={200: UserSerializerrr(many=True)}, + tags=['Users'], + ) def get(self, request): queryset = User.objects.all() serializer = UserSerializerrr(queryset, many=True) @@ -28,7 +32,8 @@ class UserList(APIView): 'username': openapi.Schema(type=openapi.TYPE_STRING) }, ), - security=[] + security=[], + tags=['Users'], ) def post(self, request): serializer = UserSerializerrr(request.data) @@ -36,17 +41,17 @@ class UserList(APIView): serializer.save() return Response(serializer.data, status=status.HTTP_201_CREATED) - @swagger_auto_schema(operation_id="users_dummy", operation_description="dummy operation") + @swagger_auto_schema(operation_id="users_dummy", operation_description="dummy operation", tags=['Users']) def patch(self, request): pass -@swagger_auto_schema(method='put', request_body=UserSerializerrr) +@swagger_auto_schema(method='put', request_body=UserSerializerrr, tags=['Users']) @swagger_auto_schema(methods=['get'], manual_parameters=[ openapi.Parameter('test', openapi.IN_QUERY, "test manual param", type=openapi.TYPE_BOOLEAN), ], responses={ 200: openapi.Response('response description', UserSerializerrr), -}) +}, tags=['Users']) @api_view(['GET', 'PUT']) def user_detail(request, pk): """user_detail fbv docstring""" diff --git a/tests/reference.yaml b/tests/reference.yaml index 852bba9..d6a4805 100644 --- a/tests/reference.yaml +++ b/tests/reference.yaml @@ -761,7 +761,7 @@ paths: items: $ref: '#/definitions/UserSerializerrr' tags: - - users + - Users post: operationId: users_create description: apiview post description override @@ -787,7 +787,7 @@ paths: username: type: string tags: - - users + - Users security: [] patch: operationId: users_dummy @@ -797,7 +797,7 @@ paths: '200': description: '' tags: - - users + - Users parameters: [] /users/{id}/: get: @@ -814,7 +814,7 @@ paths: schema: $ref: '#/definitions/UserSerializerrr' tags: - - users + - Users put: operationId: users_update description: user_detail fbv docstring @@ -830,7 +830,7 @@ paths: schema: $ref: '#/definitions/UserSerializerrr' tags: - - users + - Users parameters: - name: id in: path