diff --git a/.idea/drf-yasg.iml b/.idea/drf-yasg.iml index cf0c775..b60958d 100644 --- a/.idea/drf-yasg.iml +++ b/.idea/drf-yasg.iml @@ -16,6 +16,8 @@ + + diff --git a/docs/conf.py b/docs/conf.py index 6349644..e44703b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -175,6 +175,7 @@ nitpick_ignore = [ ('py:class', 'type'), ('py:class', 'OrderedDict'), ('py:class', 'None'), + ('py:obj', 'None'), ('py:class', 'Exception'), ('py:class', 'collections.OrderedDict'), diff --git a/src/drf_yasg/codecs.py b/src/drf_yasg/codecs.py index 83563ea..777abac 100644 --- a/src/drf_yasg/codecs.py +++ b/src/drf_yasg/codecs.py @@ -170,7 +170,7 @@ def yaml_sane_dump(data, binary): :param dict data: the data to be dumped :param bool binary: True to return a utf-8 encoded binary object, False to return a string :return: the serialized YAML - :rtype: str,bytes + :rtype: str or bytes """ return yaml.dump(data, Dumper=SaneYamlDumper, default_flow_style=False, encoding='utf-8' if binary else None) diff --git a/src/drf_yasg/generators.py b/src/drf_yasg/generators.py index 12ba61e..345a3ed 100644 --- a/src/drf_yasg/generators.py +++ b/src/drf_yasg/generators.py @@ -203,7 +203,7 @@ class OpenAPISchemaGenerator(object): and helps clients configure their authorization credentials. :return: the security schemes usable with this API - :rtype: dict[str,dict]|None + :rtype: dict[str,dict] or None """ security_definitions = swagger_settings.SECURITY_DEFINITIONS if security_definitions is not None: @@ -217,7 +217,7 @@ class OpenAPISchemaGenerator(object): :param security_definitions: security definitions as returned by :meth:`.get_security_definitions` :return: - :rtype: dict[str,list[str]]|None + :rtype: list[dict[str,list[str]]] or None """ security_requirements = swagger_settings.SECURITY_REQUIREMENTS if security_requirements is None: diff --git a/src/drf_yasg/inspectors/base.py b/src/drf_yasg/inspectors/base.py index ff3c870..07ffc2c 100644 --- a/src/drf_yasg/inspectors/base.py +++ b/src/drf_yasg/inspectors/base.py @@ -159,7 +159,7 @@ class FieldInspector(BaseInspector): :param kwargs: extra attributes for constructing the object; if swagger_object_type is Parameter, ``name`` and ``in_`` should be provided :return: the swagger object - :rtype: openapi.Parameter,openapi.Items,openapi.Schema,openapi.SchemaRef + :rtype: openapi.Parameter or openapi.Items or openapi.Schema or openapi.SchemaRef """ return NotHandled @@ -168,7 +168,7 @@ class FieldInspector(BaseInspector): All arguments are the same as :meth:`.field_to_swagger_object`. - :rtype: openapi.Parameter,openapi.Items,openapi.Schema,openapi.SchemaRef + :rtype: openapi.Parameter or openapi.Items or openapi.Schema or openapi.SchemaRef """ return self.probe_inspectors( self.field_inspectors, 'field_to_swagger_object', field, {'field_inspectors': self.field_inspectors}, @@ -203,7 +203,7 @@ class FieldInspector(BaseInspector): - :class:`.Schema` if `swagger_object_type` is :class:`.Schema` - :class:`.Items` if `swagger_object_type` is :class:`.Parameter` or :class:`.Items` - :rtype: tuple[callable,(type[openapi.Schema],type[openapi.Items])] + :rtype: tuple[callable,(type[openapi.Schema] or type[openapi.Items])] """ assert swagger_object_type in (openapi.Schema, openapi.Parameter, openapi.Items) assert not isinstance(field, openapi.SwaggerDict), "passed field is already a SwaggerDict object" @@ -368,7 +368,7 @@ class ViewInspector(BaseInspector): :param serializers.BaseSerializer serializer: the ``Serializer`` instance :returns: the converted :class:`.Schema`, or ``None`` in case of an unknown serializer - :rtype: openapi.Schema,openapi.SchemaRef + :rtype: openapi.Schema or openapi.SchemaRef """ return self.probe_inspectors( self.field_inspectors, 'get_schema', serializer, {'field_inspectors': self.field_inspectors} diff --git a/src/drf_yasg/openapi.py b/src/drf_yasg/openapi.py index 95e6021..a7e0f22 100644 --- a/src/drf_yasg/openapi.py +++ b/src/drf_yasg/openapi.py @@ -237,8 +237,8 @@ class Swagger(SwaggerDict): :param str _prefix: api path prefix to use in setting basePath; this will be appended to the wsgi SCRIPT_NAME prefix or Django's FORCE_SCRIPT_NAME if applicable :param str _version: version string to override Info - :param dict[str,dict[str,str]] security_definitions: list of supported authentication mechanisms - :param list[dict] security: authentication mechanisms accepted by default; can be overriden in Operation + :param dict[str,dict] security_definitions: list of supported authentication mechanisms + :param list[dict[str,list[str]]] security: authentication mechanisms accepted globally :param list[str] consumes: consumed MIME types; can be overriden in Operation :param list[str] produces: produced MIME types; can be overriden in Operation :param .Paths paths: paths object @@ -402,7 +402,8 @@ class Parameter(SwaggerDict): :param str in_: parameter location :param str description: parameter description :param bool required: whether the parameter is required for the operation - :param .Schema,.SchemaRef schema: required if `in_` is ``body`` + :param schema: required if `in_` is ``body`` + :type schema: .Schema or .SchemaRef :param str type: parameter type; required if `in_` is not ``body``; must not be ``object`` :param str format: value format, see OpenAPI spec :param list enum: restrict possible values @@ -454,10 +455,13 @@ class Schema(SwaggerDict): :param str format: value format, see OpenAPI spec :param list enum: restrict possible values :param str pattern: pattern if type is ``string`` - :param dict[str,(.Schema,.SchemaRef)] properties: object properties; required if `type` is ``object`` - :param bool,.Schema,.SchemaRef additional_properties: allow wildcard properties not listed in `properties` + :param properties: object properties; required if `type` is ``object`` + :type properties: dict[str,(.Schema or .SchemaRef)] + :param additional_properties: allow wildcard properties not listed in `properties` + :type additional_properties: bool or .Schema or .SchemaRef :param list[str] required: list of requried property names - :param .Schema,.SchemaRef items: type of array items, only valid if `type` is ``array`` + :param items: type of array items, only valid if `type` is ``array`` + :type items: .Schema or .SchemaRef :param default: only valid when insider another ``Schema``\\ 's ``properties``; the default value of this property if it is not provided, must conform to the type of this Schema :param read_only: only valid when insider another ``Schema``\\ 's ``properties``; @@ -508,7 +512,7 @@ class _Ref(SwaggerDict): :param str name: referenced object name, e.g. "Article" :param str scope: reference scope, e.g. "definitions" :param type[.SwaggerDict] expected_type: the expected type that will be asserted on the object found in resolver - :param bool ignore_unresolved: allow the reference to be not defined in resolver + :param bool ignore_unresolved: do not throw if the referenced object does not exist """ super(_Ref, self).__init__() assert not type(self) == _Ref, "do not instantiate _Ref directly" @@ -543,7 +547,7 @@ class SchemaRef(_Ref): :param .ReferenceResolver resolver: component resolver which must contain the definition :param str schema_name: schema name - :param bool ignore_unresolved: allow the reference to be not defined in resolver + :param bool ignore_unresolved: do not throw if the referenced object does not exist """ assert SCHEMA_DEFINITIONS in resolver.scopes super(SchemaRef, self).__init__(resolver, schema_name, SCHEMA_DEFINITIONS, Schema, ignore_unresolved) @@ -555,7 +559,8 @@ Schema.OR_REF = (Schema, SchemaRef) def resolve_ref(ref_or_obj, resolver): """Resolve `ref_or_obj` if it is a reference type. Return it unchaged if not. - :param SwaggerDict,_Ref ref_or_obj: + :param ref_or_obj: object to derefernece + :type ref_or_obj: .SwaggerDict or ._Ref :param resolver: component resolver which must contain the referenced object """ if isinstance(ref_or_obj, _Ref): @@ -567,7 +572,8 @@ class Responses(SwaggerDict): def __init__(self, responses, default=None, **extra): """Describes the expected responses of an :class:`.Operation`. - :param dict[(str,int),.Response] responses: mapping of status code to response definition + :param responses: mapping of status code to response definition + :type responses: dict[(str or int),.Response] :param .Response default: description of the response structure to expect if another status code is returned """ super(Responses, self).__init__(**extra) @@ -583,7 +589,8 @@ class Response(SwaggerDict): """Describes the structure of an operation's response. :param str description: response description - :param .Schema,.SchemaRef schema: sturcture of the response body + :param schema: sturcture of the response body + :type schema: .Schema or .SchemaRef :param dict examples: example bodies mapped by mime type """ super(Response, self).__init__(**extra) diff --git a/src/drf_yasg/utils.py b/src/drf_yasg/utils.py index 5edac06..44bbb67 100644 --- a/src/drf_yasg/utils.py +++ b/src/drf_yasg/utils.py @@ -42,8 +42,8 @@ def swagger_auto_schema(method=None, methods=None, auto_schema=unset, request_bo :param .inspectors.SwaggerAutoSchema auto_schema: custom class to use for generating the Operation object; this overrides both the class-level ``swagger_schema`` attribute and the ``DEFAULT_AUTO_SCHEMA_CLASS`` setting, and can be set to ``None`` to prevent this operation from being generated - :param .Schema,.SchemaRef,.Serializer request_body: custom request body, or :class:`.no_body`. The value given here - will be used as the ``schema`` property of a :class:`.Parameter` with ``in: 'body'``. + :param request_body: custom request body which will be used as the ``schema`` property of a + :class:`.Parameter` with ``in: 'body'``. A Schema or SchemaRef is not valid if this request consumes form-data, because ``form`` and ``body`` parameters are mutually exclusive in an :class:`.Operation`. If you need to set custom ``form`` parameters, you can use @@ -51,6 +51,7 @@ def swagger_auto_schema(method=None, methods=None, auto_schema=unset, request_bo If a ``Serializer`` class or instance is given, it will be automatically converted into a :class:`.Schema` used as a ``body`` :class:`.Parameter`, or into a list of ``form`` :class:`.Parameter`\\ s, as appropriate. + :type request_body: .Schema or .SchemaRef or .Serializer or type[.no_body] :param .Serializer query_serializer: if you use a ``Serializer`` to parse query parameters, you can pass it here and have :class:`.Parameter` objects be generated automatically from it. @@ -75,7 +76,7 @@ def swagger_auto_schema(method=None, methods=None, auto_schema=unset, request_bo 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 + :param 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 suppressed. @@ -89,6 +90,7 @@ def swagger_auto_schema(method=None, methods=None, auto_schema=unset, request_bo * a ``Serializer`` class or instance will be converted into a :class:`.Schema` and treated as above * a :class:`.Response` object will be used as-is; however if its ``schema`` attribute is a ``Serializer``, it will automatically be converted into a :class:`.Schema` + :type responses: dict[str,(.Schema or .SchemaRef or .Response or str or .Serializer)] :param list[.FieldInspector] field_inspectors: extra serializer and field inspectors; these will be tried before :attr:`.ViewInspector.field_inspectors` on the :class:`.inspectors.SwaggerAutoSchema` instance diff --git a/tox.ini b/tox.ini index f3e37e4..4dd2267 100644 --- a/tox.ini +++ b/tox.ini @@ -1,8 +1,9 @@ [tox] -# https://docs.djangoproject.com/en/dev/faq/install/#what-python-version-can-i-use-with-django minversion = 3.3.0 isolated_build = true isolated_build_env=.package + +# https://docs.djangoproject.com/en/dev/faq/install/#what-python-version-can-i-use-with-django envlist = py{27,34,35,36}-django111-drf{37,38,39}, py{34,35,36,37}-django20-drf{37,38,39}, @@ -72,5 +73,5 @@ known_standard_library = known_third_party = coreapi,coreschema,datadiff,dj_database_url,django,django_filters,djangorestframework_camel_case, rest_framework_recursive,flex,gunicorn,inflection,pygments,pytest,rest_framework,ruamel,setuptools_scm, - swagger_spec_validator,uritemplate,user_agents,whitenoise + swagger_spec_validator,uritemplate,user_agents,whitenoise,oauth2_provider known_first_party = drf_yasg,testproj,articles,people,snippets,todo,users,urlconfs