Automated generation of real Swagger/OpenAPI 2.0 schemas from Django REST Framework code.

Overview

drf-yasg - Yet another Swagger generator

Travis CI  Codecov  ReadTheDocs  PyPI

Generate real Swagger/OpenAPI 2.0 specifications from a Django Rest Framework API.

Compatible with

  • Django Rest Framework: 3.10, 3.11, 3.12
  • Django: 2.2, 3.0, 3.1
  • Python: 3.6, 3.7, 3.8, 3.9

Only the latest patch version of each major.minor series of Python, Django and Django REST Framework is supported.

Only the latest version of drf-yasg is supported. Support of old versions is dropped immediately with the release of a new version. Please do not create issues before upgrading to the latest release available at the time. Regression reports are accepted and will be resolved with a new release as quickly as possible. Removed features will usually go through a deprecation cycle of a few minor releases.

Resources:

Heroku deploy button

OpenAPI 3.0 note

If you are looking to add Swagger/OpenAPI support to a new project you might want to take a look at drf-spectacular, which is an actively maintained new library that shares most of the goals of this project, while working with OpenAPI 3.0 schemas.

OpenAPI 3.0 provides a lot more flexibility than 2.0 in the types of API that can be described. drf-yasg is unlikely to soon, if ever, get support for OpenAPI 3.0.

Features

  • full support for nested Serializers and Schemas
  • response schemas and descriptions
  • model definitions compatible with codegen tools
  • customization hooks at all points in the spec generation process
  • JSON and YAML format for spec
  • bundles latest version of swagger-ui and redoc for viewing the generated documentation
  • schema view is cacheable out of the box
  • generated Swagger schema can be automatically validated by swagger-spec-validator
  • supports Django REST Framework API versioning with URLPathVersioning and NamespaceVersioning; other DRF or custom versioning schemes are not currently supported
redoc screenshot

Fully nested request and response schemas.

swagger-ui screenshot

Choose between redoc and swagger-ui.

model definitions screenshot

Real Model definitions.

Table of contents

Usage

0. Installation

The preferred installation method is directly from pypi:

pip install -U drf-yasg

Additionally, if you want to use the built-in validation mechanisms (see 4. Validation), you need to install some extra requirements:

pip install -U drf-yasg[validation]

1. Quickstart

In settings.py:

INSTALLED_APPS = [
   ...
   'django.contrib.staticfiles',  # required for serving swagger ui's css/js files
   'drf_yasg',
   ...
]

In urls.py:

...
from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi

...

schema_view = get_schema_view(
   openapi.Info(
      title="Snippets API",
      default_version='v1',
      description="Test description",
      terms_of_service="https://www.google.com/policies/terms/",
      contact=openapi.Contact(email="[email protected]"),
      license=openapi.License(name="BSD License"),
   ),
   public=True,
   permission_classes=[permissions.AllowAny],
)

urlpatterns = [
   url(r'^swagger(?P<format>\.json|\.yaml)$', schema_view.without_ui(cache_timeout=0), name='schema-json'),
   url(r'^swagger/$', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
   url(r'^redoc/$', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
   ...
]

This exposes 4 endpoints:

  • A JSON view of your API specification at /swagger.json
  • A YAML view of your API specification at /swagger.yaml
  • A swagger-ui view of your API specification at /swagger/
  • A ReDoc view of your API specification at /redoc/

2. Configuration

a. get_schema_view parameters

  • info - Swagger API Info object; if omitted, defaults to DEFAULT_INFO
  • url - API base url; if left blank will be deduced from the location the view is served at
  • patterns - passed to SchemaGenerator
  • urlconf - passed to SchemaGenerator
  • public - if False, includes only endpoints the current user has access to
  • validators - a list of validator names to apply on the generated schema; only ssv is currently supported
  • generator_class - schema generator class to use; should be a subclass of OpenAPISchemaGenerator
  • authentication_classes - authentication classes for the schema view itself
  • permission_classes - permission classes for the schema view itself

b. SchemaView options

  • SchemaView.with_ui(renderer, cache_timeout, cache_kwargs) - get a view instance using the specified UI renderer; one of swagger, redoc
  • SchemaView.without_ui(cache_timeout, cache_kwargs) - get a view instance with no UI renderer; same as as_cached_view with no kwargs
  • SchemaView.as_cached_view(cache_timeout, cache_kwargs, **initkwargs) - same as as_view, but with optional caching
  • you can, of course, call as_view as usual

All of the first 3 methods take two optional arguments, cache_timeout and cache_kwargs; if present, these are passed on to Django’s cached_page decorator in order to enable caching on the resulting view. See 3. Caching.

c. SWAGGER_SETTINGS and REDOC_SETTINGS

Additionally, you can include some more settings in your settings.py file. See https://drf-yasg.readthedocs.io/en/stable/settings.html for details.

3. Caching

Since the schema does not usually change during the lifetime of the django process, there is out of the box support for caching the schema view in-memory, with some sane defaults:

  • caching is enabled by the cache_page decorator, using the default Django cache backend, can be changed using the cache_kwargs argument
  • HTTP caching of the response is blocked to avoid confusing situations caused by being shown stale schemas
  • the cached schema varies on the Cookie and Authorization HTTP headers to enable filtering of visible endpoints according to the authentication credentials of each user; note that this means that every user accessing the schema will have a separate schema cached in memory.

4. Validation

Given the numerous methods to manually customize the generated schema, it makes sense to validate the result to ensure it still conforms to OpenAPI 2.0. To this end, validation is provided at the generation point using python swagger libraries, and can be activated by passing validators=['ssv'] to get_schema_view; if the generated schema is not valid, a SwaggerValidationError is raised by the handling codec.

Warning: This internal validation can slow down your server. Caching can mitigate the speed impact of validation.

The provided validation will catch syntactic errors, but more subtle violations of the spec might slip by them. To ensure compatibility with code generation tools, it is recommended to also employ one or more of the following methods:

swagger-ui validation badge

Online

If your schema is publicly accessible, swagger-ui will automatically validate it against the official swagger online validator and display the result in the bottom-right validation badge.

Offline

If your schema is not accessible from the internet, you can run a local copy of swagger-validator and set the VALIDATOR_URL accordingly:

SWAGGER_SETTINGS = {
    ...
    'VALIDATOR_URL': 'http://localhost:8189',
    ...
}
$ docker run --name swagger-validator -d -p 8189:8080 --add-host test.local:10.0.75.1 swaggerapi/swagger-validator
84dabd52ba967c32ae6b660934fa6a429ca6bc9e594d56e822a858b57039c8a2
$ curl http://localhost:8189/debug?url=http://test.local:8002/swagger/?format=openapi
{}

Using swagger-cli

https://www.npmjs.com/package/swagger-cli

$ npm install -g swagger-cli
[...]
$ swagger-cli validate http://test.local:8002/swagger.yaml
http://test.local:8002/swagger.yaml is valid

Manually on editor.swagger.io

Importing the generated spec into https://editor.swagger.io/ will automatically trigger validation on it. This method is currently the only way to get both syntactic and semantic validation on your specification. The other validators only provide JSON schema-level validation, but miss things like duplicate operation names, improper content types, etc

5. Code generation

You can use the specification outputted by this library together with swagger-codegen to generate client code in your language of choice:

$ docker run --rm -v ${PWD}:/local swaggerapi/swagger-codegen-cli generate -i /local/tests/reference.yaml -l javascript -o /local/.codegen/js

See the github page linked above for more details.

6. Example project

For additional usage examples, you can take a look at the test project in the testproj directory:

$ git clone https://github.com/axnsan12/drf-yasg.git
$ cd drf-yasg
$ virtualenv venv
$ source venv/bin/activate
(venv) $ cd testproj
(venv) $ python -m pip install -U pip setuptools
(venv) $ pip install -U -r requirements.txt
(venv) $ python manage.py migrate
(venv) $ python manage.py runserver
(venv) $ firefox localhost:8000/swagger/

Third-party integrations

djangorestframework-camel-case

Integration with djangorestframework-camel-case is provided out of the box - if you have djangorestframework-camel-case installed and your APIView uses CamelCaseJSONParser or CamelCaseJSONRenderer, all property names will be converted to camelCase by default.

djangorestframework-recursive

Integration with djangorestframework-recursive is provided out of the box - if you have djangorestframework-recursive installed.

Comments
  • Redoc will never display in urls correctly

    Redoc will never display in urls correctly

    Ever since I have installed drf-yasg (Almost 6 months ago), I cannot seem to get redoc to work correctly.

    Here is the normal error I get:

    "http://127.0.0.1:8000/api/v1/redoc/?format=openapi" is not a valid JSON Schema
    Stack trace
    SyntaxError: "http://127.0.0.1:8000/api/v1/redoc/?format=openapi" is not a valid JSON Schema
        at Function.syntax (http://127.0.0.1:8000/static/drf-yasg/redoc/redoc.min.js:55:18937)
        at http://127.0.0.1:8000/static/drf-yasg/redoc/redoc.min.js:73:51233
    
    ReDoc Version: 2.0.0-alpha.25 
    

    Here is my usual url layout for swagger and redoc:

    swagger_info = openapi.Info(
        title="something api",
        default_version='v1',
        description="""something API Swagger Definition""",  # noqa
        terms_of_service="https://www.something.com/policies/terms/",
        contact=openapi.Contact(email="[email protected]"),
        license=openapi.License(name="MIT License"),
    )
    
    SchemaView = get_schema_view(
        validators=['ssv', 'flex'],
        public=True,
        permission_classes=(permissions.IsAuthenticated,),
    )
    
    ...
    
    url(r'^swagger(?P<format>\.json|\.yaml)$', SchemaView.without_ui(cache_timeout=None), name='schema-json'),
        url(r'^swagger/$', SchemaView.with_ui('swagger', cache_timeout=None), name='schema-swagger-ui'),
        url(r'^redoc/$', SchemaView.with_ui('redoc', cache_timeout=None), name='schema-redoc'),
    

    And my settings:

    SWAGGER_SETTINGS = {
        'LOGIN_URL': '/session/auth/login',
        'LOGOUT_URL': '/session/auth/logout',
        'DEFAULT_INFO': 'api.urls.swagger_info',
        'SECURITY_DEFINITIONS': {
            'Basic': {
                'type': 'basic'
            },
        },
        'APIS_SORTER': 'alpha',
        'SUPPORTED_SUBMIT_METHODS': ['get', 'post', 'put', 'delete', 'patch'],
        'OPERATIONS_SORTER': 'alpha'
    }
    REDOC_SETTINGS = {
        'LAZY_RENDERING': True,
    }
    

    Quick note: if I change permissions to permissions.AllowAny Redoc fails but validation still works.

    bug 
    opened by SultanSGillani 24
  • Incompatibility with latest DRF 3.12.0

    Incompatibility with latest DRF 3.12.0

    Encode has just released the new version of DRF django-rest-framework 3.12.0 which has dropped all compat support to Django < 2 urls

    Affected import in dry-yasg

    from rest_framework.compat import URLPattern, URLResolver, get_original_route
    

    DRF merged PR DRF Commit

    opened by fasih 23
  • oauth2 flow

    oauth2 flow

    Hi!

    Thank you for this amazing package :).

    We are implementing an oauth2 flow with Google and after converting token to our application. For that, we are using django-rest-framework-social-oauth2.

    This is our SWAGGER_SETTINGS:

    SWAGGER_SETTINGS = {
        "USE_SESSION_AUTH": False,
        "SECURITY_DEFINITIONS": {
            "api_key": {
                "type": "apiKey",
                "name": "access_token",
                "in": "header"
            },
            "google_oauth": {
                "type": "oauth2",
                "authorizationUrl": "http://127.0.0.1:8000/auth/login/google-oauth2",
                "flow": "implicit",
                "scopes": {
                    "write:admin": "You are God",
                    "read:customer": "You are a simple human"
                }
            }
        }
    }
    

    So when we click con "Authorize" button we introduce the client_id and the scope. After that, we are redirected to Google for login and then we are back to our swagger page but we are not authenticated. After Google authorization we need to convert token in order to be authenticated with our application but i don't know how to do that.

    The flow is GET /auth/login/google-oauth2/ GET /auth/login/google-oauth2/ GET /auth/complete/google-oauth2/ GET /

    Can you please help me?

    Thanks in advance :).

    enhancement 
    opened by andruten 20
  • Django 4.0 File Not Found Error

    Django 4.0 File Not Found Error

    I'm trying to run drf-yasg with Django 4.0 and Whitenoise. I keep getting file not found errors shown below when I run python manage.py collectstatic. Any suggestions how to solve this?

    whitenoise.storage.MissingFileError: The file 'drf-yasg/redoc-old/redoc.min.map' could not be found with <whitenoise.storage.CompressedManifestStaticFilesStorage object 
    
    The JS file 'drf-yasg/redoc-old/redoc.min.js' references a file which could not be found:
     drf-yasg/redoc-old/redoc.min.map
    
    opened by aibharata 17
  • Actions

    Actions

    As mentioned in #739 Travis CI is no longer running CI for free. This PR allows Github actions to run unit tests. This will allow us to continue approving PRs.

    The tox environments for linters, djmaster and docs have been bound to explicit python versions rather than rely on CI environment variables for this.

    The djmaster testenv until now has been allowed to fail. This is now made explicit with a tox flag. It is still a useful check as it offers diagnostic information about future compatibility.

    opened by JoelLefkowitz 17
  • drf_yasg incompatible with django_rest_framework 3.10

    drf_yasg incompatible with django_rest_framework 3.10

    When the application starts library throws ImportError File "/home/anatoliy/Projects/Python/skippplatform/skipro/skipro/urls/dev.py", line 8, in <module> from drf_yasg.generators import OpenAPISchemaGenerator File "/home/anatoliy/.local/share/virtualenvs/skipro-hLwcq6KW/lib/python3.6/site-packages/drf_yasg/generators.py", line 11, in <module> from rest_framework.schemas.generators import SchemaGenerator, endpoint_ordering, get_pk_name ImportError: cannot import name 'SchemaGenerator' This happens because in new version SchemaGenerator was renamed to BaseSchemaGenerator.

    opened by platonoff-dev 17
  • Change

    Change "Response content type"

    Hi,

    i need to change the shown "Response content type" of one of my api from application/json to text/plain according to the response header ( that is content-type: text/plain ).

    Is there any way to change to do this?

    Thank you

    opened by fvitello 14
  • Fix duration field inspector

    Fix duration field inspector

    Durations should be represented as an openapi.TYPE_STRING so swagger and other tools do not prevent valid input ("00:10:00" is valid, but not a number)

    See:

    https://www.django-rest-framework.org/api-guide/fields/#durationfield and https://docs.djangoproject.com/en/3.0/ref/utils/#django.utils.dateparse.parse_duration

    opened by terencehonles 14
  • Use unambiguous ref names

    Use unambiguous ref names

    serializer type name may be ambiguous, e.g. in different applications of the same project one may have different Account with the same serializer class name but with different fields, etc. In current implementation they will have the same $ref name in API spec which will lead to improper API representation. Adding module name to ref name should solve this problem.

    opened by kammala 14
  • [question] Example for Response Objects

    [question] Example for Response Objects

    I was wondering is there anyway to add an Example Object to the Response Object? I also see it is in the openapi.py.

    I looked through the code and when I manually set Responses it's generate an Open API response at https://github.com/axnsan12/drf-yasg/blob/master/src/drf_yasg/inspectors/view.py#L234

    Is there anyway to get it to set the example? If not I am willing to figure out how to get it working.

    question 
    opened by vinayan3 14
  • Calling .get_object() inside .get_serializer_class() raises AssertionError

    Calling .get_object() inside .get_serializer_class() raises AssertionError

    Tested on the example project "testproj". Steps:

    1. In view SnippetDetail, commented out serializer_class.
    2. Added a method get_serializer_class, calling self.get_object() inside it
    3. Opened http://localhost:8000/swagger/
    4. AssertionError raised. Exception Type: AssertionError at /swagger/ Exception Value: Expected view SnippetDetail to be called with a URL keyword argument named "pk". Fix your URL conf, or set the .lookup_field attribute on the view correctly.
    bug documentation 
    opened by 27149chen 14
  • FormParser and JSONParser in a ViewSet

    FormParser and JSONParser in a ViewSet

    When I use JSONParser and FormParser in the same ViewSet I got this error:

    drf_yasg.errors.SwaggerGenerationError: cannot add form parameters when the request has a request body; did you forget to set an appropriate parser class on the view?
    
    

    I need both parser in the viewset, How could I do it?

    opened by OmarSRolo 0
  • Plans to update swagger-ui package

    Plans to update swagger-ui package

    Feature Request

    Description

    At the moment drf-yasg depends on a rather dated version 4.1.3 of swagger-ui (released in Dec 2021) Since then, quite a few changes and bug fixes (including security issues) have been introduced: https://github.com/swagger-api/swagger-ui/compare/v4.1.3...v4.15.3

    Do project maintainers have plans to use newer version of swagger-ui?

    Thanks

    Describe the solution you'd like

    Ideally, update swagger-ui to the latest available version.

    Describe alternatives you've considered

    N/A

    opened by kowalcj0 0
  • Live demo not working

    Live demo not working

    Bug Report

    Description

    Clicking on the live demo in the documentation opens an app error page

    Is this a regression?

    not sure

    Minimal Reproduction

    goto https://drf-yasg-demo.herokuapp.com/
    

    Stack trace / Error message

    An error occurred in the application and your page could not be served. If you are the application owner, check your logs for details. You can do this from the Heroku CLI with the command
    
    opened by a-nassif 0
  • Hide read_only=True nested serializers from data

    Hide read_only=True nested serializers from data

    1. Use "allOf" OpenAPI property to combine $ref object with extra parameters with $ref object
    2. Hide definition from request payload representation if read_only=True argument was provided for a nested serializer
    3. Show "description" for a $ref if "help_text" was provided for a nested serializer
    opened by curiousKonstantin 1
  • Responses with Nested Serializers

    Responses with Nested Serializers

    Feature Request

    I'd like to be able to nest serializers within the response documentation under string keys.

    Description

    In my api, all of our responses are nested under a "data" key like so:

    {
      "data": {
        "first_name": "Foo",
        "email": "[email protected]"
      },
      "message": "User account successfully created!"
    }
    

    To achieve this response the routes return responses that look something like this...

            return Response(
                ResponseSerializer(
                    dict(
                        data=UserSerializer(user).data,
                        message="User account successfully created!",
                    )
                ).data,
                status=status.HTTP_200_OK,
            )
    

    Describe the solution you'd like

    I'd like to be able to do this:

    USER_RESPONSES = {
        200: {
            "data": UserSerializer(),
            "message": "User account successfully created!"
        }
    }
    

    However that doesn't work, so I'm forced to manually write out all the attributes within the UserSerializer again within the documentation.

    Describe alternatives you've considered

    Are there any workarounds? I've investigated, but I haven't been able to find any good options for how to achieve this behaviour.

    opened by jamesstonehill 0
Releases(1.21.4)
  • 1.21.4(Sep 27, 2022)

  • 1.21.3(Jul 18, 2022)

    FIXED: Set generator url for swagger_settings.DEFAULT_API_URL (#682) FIXED: Check fields for allow_null attribute (#688) FIXED: Encode pytz object field as a string by default (#717) FIXED: Handle errors rendering with TemplateHTMLRenderer (#742)

    Source code(tar.gz)
    Source code(zip)
  • 1.21.2(Jul 18, 2022)

  • 1.21.1(Jul 17, 2022)

    FIXED: Refer to permission_classes as a tuple (#678) IMPROVED: Document drf-extra-fields base64 integration (#445) ADDED: Added many support to example code (#695) ADDED: Allow specifying response as a reference (#757) FIXED: Fix old spelling errors and add a cspell configuration (#796) FIXED: Remove universal wheel, python 2 is unsupported (#782) FIXED: Fix duration field inspector (#549)

    Source code(tar.gz)
    Source code(zip)
  • 1.21.0(Jul 15, 2022)

  • 1.20.3(Jul 15, 2022)

  • 1.20.0(Oct 25, 2020)

    • IMPROVED: updated swagger-ui to version 3.36.0
    • IMPROVED: updated ReDoc to version 2.0.0-rc.40
    • FIXED: fixed compatibility with Django Rest Framework 3.12
    • FIXED: fixed compatibility with Python 3.9 typing generics
    • FIXED: dropped support for obsolete django.conf.settings.LOGOUT_URL (#646)

    Support was dropped for Python 2.7, DRF 3.8, DRF 3.9. Requirements are now: Python>=3.6, Django>=2.2, DRF>=3.10

    The 1.18 and 1.19 series was skipped to avoid confusion with the drf-yasg2 fork. I would also like to take this opportunity to extend my apologies to the community at large for the large gap in the maintenance of drf-yasg and the problems it has caused.

    Source code(tar.gz)
    Source code(zip)
  • 1.17.1(Oct 25, 2020)

    Release date: Feb 17, 2020

    • FIXED: fixed compatibility issue with CurrentUserDefault in Django Rest Framework 3.11
    • FIXED: respect USERNAME_FIELD in generate_swagger command (#486)

    Support was dropped for Python 3.5, Django 2.0, Django 2.1, DRF 3.7

    Source code(tar.gz)
    Source code(zip)
  • 1.17.0(Oct 2, 2019)

    • ADDED: added JSONFieldInspector for JSONField support (#417)
    • IMPROVED: updated swagger-ui to version 3.23.11
    • IMPROVED: updated ReDoc to version 2.0.0-rc.14 (#398)
    • FIXED: fixed a type hint support issue (#428, #450)
    • FIXED: fixed packaging issue caused by a missing requirement (#412)
    Source code(tar.gz)
    Source code(zip)
  • 1.16.1(Jul 16, 2019)

  • 1.16.0(Jul 16, 2019)

    Release date: Jun 13, 2019

    • ADDED: added reference_resolver_class attribute hook to SwaggerAutoSchema (#350)
    • ADDED: added operation_keys attribute to SwaggerAutoSchema, along with __init__ parameter (#355)
    • FIXED: fixed potential crash on issubclass check without isclass check
    Source code(tar.gz)
    Source code(zip)
  • 1.15.1(Jun 13, 2019)

    • IMPROVED: updated swagger-ui to version 3.22.3
    • IMPROVED: updated ReDoc to version 2.0.0-rc.8-1
    • FIXED: fixed an issue with inspection of typing hints on Python 2.7 (#363)
    • FIXED: fixed an issue with inspection of typing hints on Python 3.7 (#371)

    Python 3.4 support has been dropped!

    Source code(tar.gz)
    Source code(zip)
  • 1.15.0(Apr 1, 2019)

    • ADDED: added is_list_view and has_list_response extension points to SwaggerAutoSchema (#331)
    • IMPROVED: updated swagger-ui to version 3.22.0
    • IMPROVED: updated ReDoc to version 2.0.0-rc.4
    • FIXED: ListModelMixin will now always be treated as a list view (#306)
    • FIXED: non-primtive values in field choices will now be handled properly (#340)

    🎉 400 commits 🎉

    Source code(tar.gz)
    Source code(zip)
  • 1.14.0(Mar 3, 2019)

    • IMPROVED: updated swagger-ui to version 3.21.0
    • FIXED: implicit ref_name collisions will now throw an exception
    • FIXED: RecursiveField will now also work as a child of ListSerializer (#321)
    • FIXED: fixed minLength and maxLength for ListSerializer and ListField
    • FIXED: the items property of Schema, Parameter and Items objects was renamed to items_; this is a mildly breaking change and was needed to fix the collision with the items method of dict (#308)
    • REMOVED: the get_summary and get_description methods have been removed (previously deprecated in 1.12.0)
    Source code(tar.gz)
    Source code(zip)
  • 1.13.0(Mar 3, 2019)

    • IMPROVED: type hint inspection is now supported for collections and Optional (#272)
    • IMPROVED: updated swagger-ui to version 3.20.5
    • IMPROVED: updated ReDoc to version 2.0.0-rc.2
    • DEPRECATED: quietly dropped support for the flex validator; it will still work if the library is installed, but the setup.py requirement was removed and the validator will be silently skipped if not installed (#285)
    Source code(tar.gz)
    Source code(zip)
  • 1.12.1(Dec 28, 2018)

    • IMPROVED: updated ReDoc to version 2.0.0-rc.0
    • FIXED: management command will now correctly fall back to DEFAULT_VERSION for mock request
    • FIXED: fixed bad "raised exception during schema generation" warnings caused by missing self parameter
    Source code(tar.gz)
    Source code(zip)
  • 1.12.0(Dec 24, 2018)

    • ADDED: get_security_definitions and get_security_requirements hooks to OpenAPISchemaGenerator
    • ADDED: added get_summary_and_description and split_summary_from_description extension points to SwaggerAutoSchema to allow for better customisation
    • IMPROVED: updated swagger-ui to version 3.20.4
    • IMPROVED: paginator next and previous fields are now marked as x-nullable (#263)
    • IMPROVED: added the tags argument to swagger_auto_schema (#259)
    • IMPROVED: type of enum will now be automatically detected from ChoiceField if all choices values are objects of the same Python class (#264)
    • IMPROVED: SwaggerValidationError details will now be logged and shown in the exception message
    • FIXED: user implementations of get_queryset, get_parsers and get_renderers will no longer be bypassed
    • FIXED: fixed handling of lazy objects in user-supplied values
    • FIXED: read_only serializer fields will be correctly ignored when generating form parameters (#261)
    • FIXED: fixed incorrect return type from UIRenderer (#268)
    • FIXED: fixed incosistent ordering of global securityDefinitions and security objects
    • DEPRECATED: the get_summary and get_description extension points have been deprecated in favor of the new get_summary_and_description, and will be removed in a future release

    IMPORTANT PACKAGING NOTE

    Starting with this version, the setup_requires argument was dropped from setup.py in favor of build-system.requires in pyproject.toml . This means that for correctly building or installing from sdist, you will need to use a PEP517/PEP518 compliant tool (tox>=3.3.0, setuptools>=40, pip>=10.0, pep517.build) or manually install the build requirements yourself (just setuptools and setuptools-scm, for now).

    Additionally, for correct package version detection, a full git checkout is required when building (this was always the case). Building without .git or without setuptools-scm will result in a distribution with a version like drf-yasg-1!0.0.0.dev0+noscm.00000167d19bd859.

    Source code(tar.gz)
    Source code(zip)
  • 1.11.1(Nov 29, 2018)

    • IMPROVED: updated swagger-ui to version 3.20.1
    • IMPROVED: updated ReDoc to version 2.0.0-alpha.41
    • FIXED: minLength and maxLength will now also work for ListSerializer in addition to ListField
    • FIXED: MultipleChoiceField will now use the multi collectionFormat where appropriate (#257)
    • FIXED: the format, pattern, enum, min_length and max_length attributes of coreschema.Schema will now be persited into the converted openapi.Parameter (#212, #233)
    Source code(tar.gz)
    Source code(zip)
  • 1.11.0(Oct 14, 2018)

    • ADDED: PERSIST_AUTH, REFETCH_SCHEMA_WITH_AUTH, REFETCH_SCHEMA_ON_LOGOUT settings and related javascript implementation for persisting authentication data to swagger-ui localStorage
    • IMPROVED: UI-enabled views will now no longer generate the full specification document twice; the HTML part of the view will only generate a barebones Swagger object with no paths and definitions
    • IMPROVED: added the FETCH_SCHEMA_WITH_QUERY setting to enable fetching of the schema document using query parameters passed to the UI view (#208)
    • IMPROVED: added support for the very common x-nullable extension (#217)
    • IMPROVED: extensibility of some classes was improved by adding more extension points, together with more blocks for swagger-ui.html/redoc.html and some JavaScript hooks in swagger-ui-init.js
    • FIXED: removed usage of inspect.signature on python 2.7 (#222)
    Source code(tar.gz)
    Source code(zip)
  • 1.10.2(Sep 13, 2018)

    • ADDED: added the DISPLAY_OPERATION_ID swagger-ui setting
    • IMPROVED: updated ReDoc to version 2.0.0-alpha.38
    • IMPROVED: Operation summary will now be parsed from multi-line view method docstrings (#205)
    • IMPROVED: pattern will now work on any field with a RegexValidator (would previously not appear on fields with special formats such as EmailField)
    • FIXED: fixed an issue with RelatedFieldInspector handling of nested serializers
    • FIXED: fixed handling of reverse_lazy in URL settings (#209)
    Source code(tar.gz)
    Source code(zip)
  • 1.10.1(Sep 9, 2018)

    • ADDED: added the SPEC_URL setting for controlling the download link in swagger-ui and ReDoc
    • ADDED: updated ReDoc settings (added NATIVE_SCROLLBARS and REQUIRED_PROPS_FIRST)
    • ADDED: added extra_styles and extra_scripts blocks to ui templates (#178)
    • IMPROVED: updated swagger-ui to version 3.18.2
    • IMPROVED: updated ReDoc to version 2.0.0-alpha.37
    • FIXED: stopped generating invalid OpenAPI by improper placement of readOnly Schemas
    • FIXED: fixed broken CSS when USE_SESSION_AUTH=False
    • FIXED: fixed implementation of operation_summary and deprecated (#194, #198)
    • FIXED: fixed a bug related to nested typing hints (#195)
    • FIXED: removed dependency on future (#196)
    • FIXED: removed exceptions loged for fields with default=None (#203)
    • FIXED: fixed request_body=no_body handling and related tests (#188, #199)
    Source code(tar.gz)
    Source code(zip)
  • 1.10.0(Aug 7, 2018)

    • ADDED: added EXCLUDED_MEDIA_TYPES setting for controlling produces MIME type filtering (#158)
    • 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 (#137, #175, #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: updated swagger-ui to version 3.18.0
    • IMPROVED: added support for Python 3.7 and Django 2.1 (#176)
    • IMPROVED: swagger_schema_fields will now also work on serializer Fields (#167)
    • IMPROVED: ref_name collisions will now log a warning message (#156)
    • IMPROVED: added operation_summary and deprecated arguments to swagger_auto_schema (#149, #173)
    • FIXED: made swagger_auto_schema work with DRF 3.9 @action mappings (#177)
    Source code(tar.gz)
    Source code(zip)
  • 1.9.2(Aug 3, 2018)

    • IMPROVED: updated swagger-ui to version 3.17.6
    • IMPROVED: updated ReDoc to version 2.0.0-alpha.32
    • IMPROVED: added --api-version argument to the generate_swagger management command (#170)
    • FIXED: corrected various documentation typos (#160, #162, #171, #172)
    • FIXED: made generate_swagger work for projects without authentication (#161)
    • FIXED: fixed SafeText interaction with YAML codec (#159)
    Source code(tar.gz)
    Source code(zip)
  • 1.9.1(Jun 29, 2018)

    • IMPROVED: added a swagger_fake_view marker to more easily detect mock views in view methods; getattr(self, 'swagger_fake_view', False) inside a view method like get_serializer_class will tell you if the view instance is being used for swagger schema introspection (#154)
    • IMPROVED: updated swagger-ui to version 3.17.1
    • IMPROVED: updated ReDoc to version 2.0.0-alpha.25
    • FIXED: fixed wrong handling of duplicate urls in urlconf (#155)
    • FIXED: fixed crash when passing None as a response override (#148)
    Source code(tar.gz)
    Source code(zip)
  • 1.9.0(Jun 29, 2018)

    Release date: Jun 16, 2018

    • ADDED: added DEFAULT_GENERATOR_CLASS setting and --generator-class argument to the generate_swagger management command (#140)
    • FIXED: fixed wrongly required 'count' response field on CursorPagination (#141)
    • FIXED: fixed some cases where swagger_extra_fields would not be handlded (#142)
    • FIXED: fixed crash when encountering coreapi.Fieldss without a schema (#143)
    Source code(tar.gz)
    Source code(zip)
  • 1.8.0(May 30, 2018)

    • ADDED: added a :ref:swagger_schema_fields <swagger_schema_fields> field on serializer Meta classes for customizing schema generation (#132, #134)
    • FIXED: error responses from schema views are now rendered with JSONRenderer instead of throwing confusing errors (#130, #58)
    • FIXED: readOnly schema fields will now no longer be marked as required (#133)
    Source code(tar.gz)
    Source code(zip)
  • 1.7.4(May 30, 2018)

    Release date: May 14, 2018

    • IMPROVED: updated swagger-ui to version 3.14.2
    • IMPROVED: updated ReDoc to version 2.0.0-alpha.20
    • FIXED: ignore None return from get_operation to avoid empty Path objects in output
    • FIXED: request body is now allowed on DELETE endpoints (#118)
    Source code(tar.gz)
    Source code(zip)
  • 1.7.3(May 12, 2018)

  • 1.7.2(May 12, 2018)

    • FIXED: fixed generation of default SECURITY_REQUIREMENTS to match documented behaviour
    • FIXED: ordering of SECURITY_REQUIREMENTS and SECURITY_DEFINITIONS is now stable
    Source code(tar.gz)
    Source code(zip)
  • 1.7.1(May 5, 2018)

    • IMPROVED: updated swagger-ui to version 3.14.1
    • IMPROVED: set swagger-ui showCommonExtensions to True by default and add SHOW_COMMON_EXTENSIONS setting key
    • IMPROVED: set min_length=1 when allow_blank=False (#112, thanks to @elnappo)
    • FIXED: made documentation ordering of SwaggerDict extra attributes stable
    Source code(tar.gz)
    Source code(zip)
Swagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.

Introduction Swagger UI allows anyone — be it your development team or your end consumers — to visualize and interact with the API’s resources without

Swagger 23.2k Dec 29, 2022
Swagger Documentation Generator for Django REST Framework: deprecated

Django REST Swagger: deprecated (2019-06-04) This project is no longer being maintained. Please consider drf-yasg as an alternative/successor. I haven

Marc Gibbons 2.6k Jan 3, 2023
SqlAlchemy Flask-Restful Swagger Json:API OpenAPI

SAFRS: Python OpenAPI & JSON:API Framework Overview Installation JSON:API Interface Resource Objects Relationships Methods Custom Methods Class Method

Thomas Pollet 361 Nov 16, 2022
Flask-Rebar combines flask, marshmallow, and swagger for robust REST services.

Flask-Rebar Flask-Rebar combines flask, marshmallow, and swagger for robust REST services. Features Request and Response Validation - Flask-Rebar reli

PlanGrid 223 Dec 19, 2022
A swagger tool for tornado, using python to write api doc!

SwaggerDoc About A swagger tool for tornado, using python to write api doc! Installation pip install swagger-doc Quick Start code import tornado.ioloo

aaashuai 1 Jan 10, 2022
Generating a report CSV and send it to an email - Python / Django Rest Framework

Generating a report in CSV format and sending it to a email How to start project. Create a folder in your machine Create a virtual environment python3

alexandre Lopes 1 Jan 17, 2022
API spec validator and OpenAPI document generator for Python web frameworks.

API spec validator and OpenAPI document generator for Python web frameworks.

1001001 249 Dec 22, 2022
Test utility for validating OpenAPI documentation

DRF OpenAPI Tester This is a test utility to validate DRF Test Responses against OpenAPI 2 and 3 schema. It has built-in support for: OpenAPI 2/3 yaml

snok 106 Jan 5, 2023
graphical orbitational simulation of solar system planets with real values and physics implemented so you get a nice elliptical orbits. you can change timestamp value or scale from source code idc.

solarSystemOrbitalSimulation graphical orbitational simulation of solar system planets with real values and physics implemented so you get a nice elli

Mega 3 Mar 3, 2022
Automated Integration Testing and Live Documentation for your API

Automated Integration Testing and Live Documentation for your API

ScanAPI 1.3k Dec 30, 2022
epub2sphinx is a tool to convert epub files to ReST for Sphinx

epub2sphinx epub2sphinx is a tool to convert epub files to ReST for Sphinx. It uses Pandoc for converting HTML data inside epub files into ReST. It cr

Nihaal 8 Dec 15, 2022
A simple document management REST based API for collaboratively interacting with documents

documan_api A simple document management REST based API for collaboratively interacting with documents.

Shahid Yousuf 1 Jan 22, 2022
Żmija is a simple universal code generation tool.

Żmija Żmija is a simple universal code generation tool. It is intended to be used as a means to generate code that is both efficient and easily mainta

Adrian Samoticha 2 Nov 23, 2021
Fully reproducible, Dockerized, step-by-step, tutorial on how to mock a "real-time" Kafka data stream from a timestamped csv file. Detailed blog post published on Towards Data Science.

time-series-kafka-demo Mock stream producer for time series data using Kafka. I walk through this tutorial and others here on GitHub and on my Medium

Maria Patterson 26 Nov 15, 2022
Testing-crud-login-drf - Creation of an application in django on music albums

testing-crud-login-drf Creation of an application in django on music albums Befo

Juan 1 Jan 11, 2022
EasyModerationKit is an open-source framework designed to moderate and filter inappropriate content.

EasyModerationKit is a public transparency statement. It declares any repositories and legalities used in the EasyModeration system. It allows for implementing EasyModeration into an advanced character/word/phrase detection system.

Aarav 1 Jan 16, 2022
Run `black` on python code blocks in documentation files

blacken-docs Run black on python code blocks in documentation files. install pip install blacken-docs usage blacken-docs provides a single executable

Anthony Sottile 460 Dec 23, 2022
The source code that powers readthedocs.org

Welcome to Read the Docs Purpose Read the Docs hosts documentation for the open source community. It supports Sphinx docs written with reStructuredTex

Read the Docs 7.4k Dec 25, 2022
Documentation of the QR code found on new Austrian ID cards.

Austrian ID Card QR Code This document aims to be a complete documentation of the format used in the QR area on the back of new Austrian ID cards (Per

Gabriel Huber 9 Dec 12, 2022