diff --git a/docs/changelog.rst b/docs/changelog.rst index 4a2cdb9..c2cdfb4 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -9,12 +9,14 @@ Changelog *Release date: TBD, 2018* -- **IMPROVED:** added support for ``SerializerMethodField``, via the ``swagger_serializer_method`` decorator for the +- **ADDED:** added support for ``SerializerMethodField``, via the ``swagger_serializer_method`` decorator for the method field, and support for Python 3.5 style type hinting of the method field return type (:issue:`137`, :pr:`175`, :pr:`179`) *NOTE:* in order for this to work, you will have to add the new ``drf_yasg.inspectors.SerializerMethodFieldInspector`` to your ``DEFAULT_FIELD_INSPECTORS`` array if you changed it from the default value +- **IMPROVED:** added ``operation_summary`` and ``deprecated`` arguments to ``swagger_auto_schema`` + (:issue:`149`, :issue:`173`) ********* **1.9.2** diff --git a/src/drf_yasg/inspectors/view.py b/src/drf_yasg/inspectors/view.py index 03c3686..c2d468e 100644 --- a/src/drf_yasg/inspectors/view.py +++ b/src/drf_yasg/inspectors/view.py @@ -34,8 +34,10 @@ class SwaggerAutoSchema(ViewInspector): operation_id = self.get_operation_id(operation_keys) description = self.get_description() + summary = self.get_summary() security = self.get_security() assert security is None or isinstance(security, list), "security must be a list of securiy requirement objects" + deprecated = self.is_deprecated() tags = self.get_tags(operation_keys) responses = self.get_responses() @@ -43,12 +45,14 @@ class SwaggerAutoSchema(ViewInspector): return openapi.Operation( operation_id=operation_id, description=force_real_str(description), + summary=force_real_str(summary), responses=responses, parameters=parameters, consumes=consumes, produces=produces, tags=tags, - security=security + security=security, + deprecated=deprecated ) def get_request_body_parameters(self, consumes): @@ -325,6 +329,14 @@ class SwaggerAutoSchema(ViewInspector): description = self._sch.get_description(self.path, self.method) return description + def get_summary(self): + """Return a summary description for this operation. + + :return: the summary + :rtype: str + """ + return self.overrides.get('operation_summary', None) + def get_security(self): """Return a list of security requirements for this operation. @@ -335,6 +347,14 @@ class SwaggerAutoSchema(ViewInspector): :rtype: list[dict[str,list[str]]]""" return self.overrides.get('security', None) + def is_deprecated(self): + """Return ``True`` if this operation is to be marked as deprecated. + + :return: deprecation status + :rtype: bool + """ + return self.overrides.get('deprecated', None) + 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. diff --git a/src/drf_yasg/utils.py b/src/drf_yasg/utils.py index 42eae6b..f0018da 100644 --- a/src/drf_yasg/utils.py +++ b/src/drf_yasg/utils.py @@ -25,9 +25,9 @@ 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, security=None, - responses=None, field_inspectors=None, filter_inspectors=None, paginator_inspectors=None, - **extra_overrides): + 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): """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 @@ -68,9 +68,11 @@ def swagger_auto_schema(method=None, methods=None, auto_schema=unset, request_bo :param str operation_id: operation ID override; the operation ID must be unique accross the whole API :param str operation_description: operation description override + :param str operation_summary: operation summary string :param list[dict] security: security requirements override; used to specify which authetication mechanism is requried to call this API; an empty list marks the endpoint as unauthenticated (i.e. removes all accepted authentication schemes), and ``None`` will inherit the top-level secuirty requirements + :param bool deprecated: deprecation status for operation :param dict[str,(.Schema,.SchemaRef,.Response,str,Serializer)] responses: a dict of documented manual responses keyed on response status code. If no success (``2xx``) response is given, one will automatically be generated from the request body and http method. If any ``2xx`` response is given the automatic response is