.. role:: python(code)
:language: python
########################################
drf-yasg - Yet another Swagger generator
########################################
|actions| |nbsp| |codecov| |nbsp| |rtd-badge| |nbsp| |pypi-version| |nbsp| |gitter|
Generate **real** Swagger/OpenAPI 2.0 specifications from a Django Rest Framework API.
Compatible with
- **Django Rest Framework**: 3.10, 3.11, 3.12, 3.13, 3.14
- **Django**: 2.2, 3.0, 3.1, 3.2, 4.0, 4.1, 4.2
- **Python**: 3.6, 3.7, 3.8, 3.9, 3.10, 3.11, 3.12
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:
* `Sources <https://github.com/axnsan12/drf-yasg>`_
* `Documentation <https://drf-yasg.readthedocs.io>`_
* `Changelog <https://drf-yasg.readthedocs.io/en/stable/changelog.html>`_
* `Live demo <https://drf-yasg-demo.herokuapp.com>`_
* `Discussion <https://app.gitter.im/#/room/#drf-yasg:gitter.im>`_
|heroku-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 <https://github.com/tfranzel/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 <https://github.com/swagger-api/swagger-ui>`_ and
`redoc <https://github.com/Rebilly/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 <https://github.com/Yelp/swagger_spec_validator>`_
- supports Django REST Framework API versioning with ``URLPathVersioning`` and ``NamespaceVersioning``; other DRF
or custom versioning schemes are not currently supported
.. figure:: https://raw.githubusercontent.com/axnsan12/drf-yasg/1.0.2/screenshots/redoc-nested-response.png
:width: 100%
:figwidth: image
:alt: redoc screenshot
**Fully nested request and response schemas.**
.. figure:: https://raw.githubusercontent.com/axnsan12/drf-yasg/1.0.2/screenshots/swagger-ui-list.png
:width: 100%
:figwidth: image
:alt: swagger-ui screenshot
**Choose between redoc and swagger-ui.**
.. figure:: https://raw.githubusercontent.com/axnsan12/drf-yasg/1.0.2/screenshots/swagger-ui-models.png
:width: 100%
:figwidth: image
:alt: model definitions screenshot
**Real Model definitions.**
*****************
Table of contents
*****************
.. contents::
:depth: 4
*****
Usage
*****
0. Installation
===============
The preferred installation method is directly from pypi:
.. code:: console
pip install --upgrade drf-yasg
Additionally, if you want to use the built-in validation mechanisms (see `4. Validation`_), you need to install
some extra requirements:
.. code:: console
pip install --upgrade drf-yasg[validation]
.. _readme-quickstart:
1. Quickstart
=============
In ``settings.py``:
.. code:: python
INSTALLED_APPS = [
...
'django.contrib.staticfiles', # required for serving swagger ui's css/js files
'drf_yasg',
...
]
In ``urls.py``:
.. code:: python
...
from django.urls import re_path
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="contact@snippets.local"),
license=openapi.License(name="BSD License"),
),
public=True,
permission_classes=(permissions.AllowAny,),
)
urlpatterns = [
path('swagger<format>/', schema_view.without_ui(cache_timeout=0), name='schema-json'),
path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
path('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
-------------------------------
- :python:`SchemaView.with_ui(renderer, cache_timeout, cache_kwargs)` - get a view instance using the
specified UI renderer; one of ``swagger``, ``redoc``
- :python:`SchemaView.without_ui(cache_timeout, cache_kwargs)` - get a view instance with no UI renderer;
same as ``as_cached_view`` with no kwargs
- :python:`SchemaView.as_cached_view(cache_timeout, cache_kwargs, **initkwargs)` - same as ``as_view``,
but with optional caching
- you can, of course, call :python:`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 :python:`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 <https://docs.djangoproject.com/en/1.11/topics/cache/#the-per-view-cache>`__
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 :python:`validators=['ssv']` to ``get_schema_view``; if the generated
schema is not valid, a :python:`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 <https://hub.docker.com/r/swaggerapi/swagger-validator/>`_ and set the ``VALIDATOR_URL`` accordingly:
.. code:: python
SWAGGER_SETTINGS = {
...
'VALIDATOR_URL': 'http://localhost:8189',
...
}
.. code:: console
$ 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
.. code:: console
$ 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 <https://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 <https://github.com/swagger-api/swagger-codegen>`_ to generate client code in your language of choice:
.. code:: console
$ 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.
.. _readme-testproj:
6. Example project
==================
For additional usage examples, you can take a look at the test project in the ``testproj`` directory:
.. code:: console
$ 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 --upgrade pip setuptools
(venv) $ pip install --upgrade -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 <https://github.com/vbabiy/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 <https://github.com/heywbj/django-rest-framework-recursive>`_ is
provided out of the box - if you have ``djangorestframework-recursive`` installed.
.. |actions| image:: https://img.shields.io/github/actions/workflow/status/axnsan12/drf-yasg/review.yml?branch=master
:target: https://github.com/axnsan12/drf-yasg/actions
:alt: GitHub Workflow Status
.. |codecov| image:: https://img.shields.io/codecov/c/github/axnsan12/drf-yasg/master.svg
:target: https://codecov.io/gh/axnsan12/drf-yasg
:alt: Codecov
.. |pypi-version| image:: https://img.shields.io/pypi/v/drf-yasg.svg
:target: https://pypi.org/project/drf-yasg/
:alt: PyPI
.. |gitter| image:: https://badges.gitter.im/drf-yasg.svg
:target: https://app.gitter.im/#/room/#drf-yasg:gitter.im
:alt: Gitter
.. |rtd-badge| image:: https://img.shields.io/readthedocs/drf-yasg.svg
:target: https://drf-yasg.readthedocs.io/
:alt: ReadTheDocs
.. |heroku-button| image:: https://www.herokucdn.com/deploy/button.svg
:target: https://heroku.com/deploy?template=https://github.com/axnsan12/drf-yasg
:alt: Heroku deploy button
.. |nbsp| unicode:: 0xA0
:trim:
drf-extra-fields
=================
Integration with `drf-extra-fields <https://github.com/Hipo/drf-extra-fields>`_ has a problem with Base64 fields.
The drf-yasg will generate Base64 file or image fields as Readonly and not required. Here is a workaround code
for display the Base64 fields correctly.
.. code:: python
class PDFBase64FileField(Base64FileField):
ALLOWED_TYPES = ['pdf']
class Meta:
swagger_schema_fields = {
'type': 'string',
'title': 'File Content',
'description': 'Content of the file base64 encoded',
'read_only': False # <-- FIX
}
def get_file_extension(self, filename, decoded_file):
try:
PyPDF2.PdfFileReader(io.BytesIO(decoded_file))
except PyPDF2.utils.PdfReadError as e:
logger.warning(e)
else:
return 'pdf'
Raw data
{
"_id": null,
"home_page": "https://github.com/axnsan12/drf-yasg",
"name": "humansignal-drf-yasg",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "drf django django-rest-framework schema swagger openapi codegen swagger-codegen documentation drf-yasg django-rest-swagger drf-openapi",
"author": "Cristi V.",
"author_email": "cristi@cvjd.me",
"download_url": "https://files.pythonhosted.org/packages/9a/f9/959d67a97b984ac63596444625ba7e318b5567be57007592d3439f9a502f/humansignal-drf-yasg-1.21.10.post1.tar.gz",
"platform": null,
"description": ".. role:: python(code)\n :language: python\n\n########################################\ndrf-yasg - Yet another Swagger generator\n########################################\n\n|actions| |nbsp| |codecov| |nbsp| |rtd-badge| |nbsp| |pypi-version| |nbsp| |gitter|\n\nGenerate **real** Swagger/OpenAPI 2.0 specifications from a Django Rest Framework API.\n\nCompatible with\n\n- **Django Rest Framework**: 3.10, 3.11, 3.12, 3.13, 3.14\n- **Django**: 2.2, 3.0, 3.1, 3.2, 4.0, 4.1, 4.2\n- **Python**: 3.6, 3.7, 3.8, 3.9, 3.10, 3.11, 3.12\n\nOnly the latest patch version of each ``major.minor`` series of Python, Django and Django REST Framework is supported.\n\n**Only the latest version of drf-yasg is supported.** Support of old versions is dropped immediately with the release\nof a new version. Please do not create issues before upgrading to the latest release available at the time. Regression\nreports are accepted and will be resolved with a new release as quickly as possible. Removed features will usually go\nthrough a deprecation cycle of a few minor releases.\n\nResources:\n\n* `Sources <https://github.com/axnsan12/drf-yasg>`_\n* `Documentation <https://drf-yasg.readthedocs.io>`_\n* `Changelog <https://drf-yasg.readthedocs.io/en/stable/changelog.html>`_\n* `Live demo <https://drf-yasg-demo.herokuapp.com>`_\n* `Discussion <https://app.gitter.im/#/room/#drf-yasg:gitter.im>`_\n\n|heroku-button|\n\n****************\nOpenAPI 3.0 note\n****************\n\nIf you are looking to add Swagger/OpenAPI support to a new project you might want to take a look at\n`drf-spectacular <https://github.com/tfranzel/drf-spectacular>`_, which is an actively maintained new library that\nshares most of the goals of this project, while working with OpenAPI 3.0 schemas.\n\nOpenAPI 3.0 provides a lot more flexibility than 2.0 in the types of API that can be described.\n``drf-yasg`` is unlikely to soon, if ever, get support for OpenAPI 3.0.\n\n\n********\nFeatures\n********\n\n- full support for nested Serializers and Schemas\n- response schemas and descriptions\n- model definitions compatible with codegen tools\n- customization hooks at all points in the spec generation process\n- JSON and YAML format for spec\n- bundles latest version of\n `swagger-ui <https://github.com/swagger-api/swagger-ui>`_ and\n `redoc <https://github.com/Rebilly/ReDoc>`_ for viewing the generated documentation\n- schema view is cacheable out of the box\n- generated Swagger schema can be automatically validated by\n `swagger-spec-validator <https://github.com/Yelp/swagger_spec_validator>`_\n- supports Django REST Framework API versioning with ``URLPathVersioning`` and ``NamespaceVersioning``; other DRF\n or custom versioning schemes are not currently supported\n\n.. figure:: https://raw.githubusercontent.com/axnsan12/drf-yasg/1.0.2/screenshots/redoc-nested-response.png\n :width: 100%\n :figwidth: image\n :alt: redoc screenshot\n\n **Fully nested request and response schemas.**\n\n.. figure:: https://raw.githubusercontent.com/axnsan12/drf-yasg/1.0.2/screenshots/swagger-ui-list.png\n :width: 100%\n :figwidth: image\n :alt: swagger-ui screenshot\n\n **Choose between redoc and swagger-ui.**\n\n.. figure:: https://raw.githubusercontent.com/axnsan12/drf-yasg/1.0.2/screenshots/swagger-ui-models.png\n :width: 100%\n :figwidth: image\n :alt: model definitions screenshot\n\n **Real Model definitions.**\n\n\n*****************\nTable of contents\n*****************\n\n.. contents::\n :depth: 4\n\n*****\nUsage\n*****\n\n0. Installation\n===============\n\nThe preferred installation method is directly from pypi:\n\n.. code:: console\n\n pip install --upgrade drf-yasg\n\nAdditionally, if you want to use the built-in validation mechanisms (see `4. Validation`_), you need to install\nsome extra requirements:\n\n.. code:: console\n\n pip install --upgrade drf-yasg[validation]\n\n.. _readme-quickstart:\n\n1. Quickstart\n=============\n\nIn ``settings.py``:\n\n.. code:: python\n\n INSTALLED_APPS = [\n ...\n 'django.contrib.staticfiles', # required for serving swagger ui's css/js files\n 'drf_yasg',\n ...\n ]\n\nIn ``urls.py``:\n\n.. code:: python\n\n ...\n from django.urls import re_path\n from rest_framework import permissions\n from drf_yasg.views import get_schema_view\n from drf_yasg import openapi\n\n ...\n\n schema_view = get_schema_view(\n openapi.Info(\n title=\"Snippets API\",\n default_version='v1',\n description=\"Test description\",\n terms_of_service=\"https://www.google.com/policies/terms/\",\n contact=openapi.Contact(email=\"contact@snippets.local\"),\n license=openapi.License(name=\"BSD License\"),\n ),\n public=True,\n permission_classes=(permissions.AllowAny,),\n )\n\n urlpatterns = [\n path('swagger<format>/', schema_view.without_ui(cache_timeout=0), name='schema-json'),\n path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),\n path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),\n ...\n ]\n\nThis exposes 4 endpoints:\n\n* A JSON view of your API specification at ``/swagger.json``\n* A YAML view of your API specification at ``/swagger.yaml``\n* A swagger-ui view of your API specification at ``/swagger/``\n* A ReDoc view of your API specification at ``/redoc/``\n\n2. Configuration\n================\n\n---------------------------------\na. ``get_schema_view`` parameters\n---------------------------------\n\n- ``info`` - Swagger API Info object; if omitted, defaults to ``DEFAULT_INFO``\n- ``url`` - API base url; if left blank will be deduced from the location the view is served at\n- ``patterns`` - passed to SchemaGenerator\n- ``urlconf`` - passed to SchemaGenerator\n- ``public`` - if False, includes only endpoints the current user has access to\n- ``validators`` - a list of validator names to apply on the generated schema; only ``ssv`` is currently supported\n- ``generator_class`` - schema generator class to use; should be a subclass of ``OpenAPISchemaGenerator``\n- ``authentication_classes`` - authentication classes for the schema view itself\n- ``permission_classes`` - permission classes for the schema view itself\n\n-------------------------------\nb. ``SchemaView`` options\n-------------------------------\n\n- :python:`SchemaView.with_ui(renderer, cache_timeout, cache_kwargs)` - get a view instance using the\n specified UI renderer; one of ``swagger``, ``redoc``\n- :python:`SchemaView.without_ui(cache_timeout, cache_kwargs)` - get a view instance with no UI renderer;\n same as ``as_cached_view`` with no kwargs\n- :python:`SchemaView.as_cached_view(cache_timeout, cache_kwargs, **initkwargs)` - same as ``as_view``,\n but with optional caching\n- you can, of course, call :python:`as_view` as usual\n\nAll of the first 3 methods take two optional arguments, ``cache_timeout`` and ``cache_kwargs``; if present,\nthese are passed on to Django\u2019s :python:`cached_page` decorator in order to enable caching on the resulting view.\nSee `3. Caching`_.\n\n----------------------------------------------\nc. ``SWAGGER_SETTINGS`` and ``REDOC_SETTINGS``\n----------------------------------------------\n\nAdditionally, you can include some more settings in your ``settings.py`` file.\nSee https://drf-yasg.readthedocs.io/en/stable/settings.html for details.\n\n\n3. Caching\n==========\n\nSince the schema does not usually change during the lifetime of the django process, there is out of the box support for\ncaching the schema view in-memory, with some sane defaults:\n\n* caching is enabled by the `cache_page <https://docs.djangoproject.com/en/1.11/topics/cache/#the-per-view-cache>`__\n decorator, using the default Django cache backend, can be changed using the ``cache_kwargs`` argument\n* HTTP caching of the response is blocked to avoid confusing situations caused by being shown stale schemas\n* the cached schema varies on the ``Cookie`` and ``Authorization`` HTTP headers to enable filtering of visible endpoints\n according to the authentication credentials of each user; note that this means that every user accessing the schema\n will have a separate schema cached in memory.\n\n4. Validation\n=============\n\nGiven the numerous methods to manually customize the generated schema, it makes sense to validate the result to ensure\nit still conforms to OpenAPI 2.0. To this end, validation is provided at the generation point using python swagger\nlibraries, and can be activated by passing :python:`validators=['ssv']` to ``get_schema_view``; if the generated\nschema is not valid, a :python:`SwaggerValidationError` is raised by the handling codec.\n\n**Warning:** This internal validation can slow down your server.\nCaching can mitigate the speed impact of validation.\n\nThe provided validation will catch syntactic errors, but more subtle violations of the spec might slip by them. To\nensure compatibility with code generation tools, it is recommended to also employ one or more of the following methods:\n\n-------------------------------\n``swagger-ui`` validation badge\n-------------------------------\n\nOnline\n^^^^^^\n\nIf your schema is publicly accessible, `swagger-ui` will automatically validate it against the official swagger\nonline validator and display the result in the bottom-right validation badge.\n\nOffline\n^^^^^^^\n\nIf your schema is not accessible from the internet, you can run a local copy of\n`swagger-validator <https://hub.docker.com/r/swaggerapi/swagger-validator/>`_ and set the ``VALIDATOR_URL`` accordingly:\n\n.. code:: python\n\n SWAGGER_SETTINGS = {\n ...\n 'VALIDATOR_URL': 'http://localhost:8189',\n ...\n }\n\n.. code:: console\n\n $ docker run --name swagger-validator -d -p 8189:8080 --add-host test.local:10.0.75.1 swaggerapi/swagger-validator\n 84dabd52ba967c32ae6b660934fa6a429ca6bc9e594d56e822a858b57039c8a2\n $ curl http://localhost:8189/debug?url=http://test.local:8002/swagger/?format=openapi\n {}\n\n---------------------\nUsing ``swagger-cli``\n---------------------\n\nhttps://www.npmjs.com/package/swagger-cli\n\n.. code:: console\n\n $ npm install -g swagger-cli\n [...]\n $ swagger-cli validate http://test.local:8002/swagger.yaml\n http://test.local:8002/swagger.yaml is valid\n\n--------------------------------------------------------------\nManually on `editor.swagger.io <https://editor.swagger.io/>`__\n--------------------------------------------------------------\n\nImporting the generated spec into https://editor.swagger.io/ will automatically trigger validation on it.\nThis method is currently the only way to get both syntactic and semantic validation on your specification.\nThe other validators only provide JSON schema-level validation, but miss things like duplicate operation names,\nimproper content types, etc\n\n5. Code generation\n==================\n\nYou can use the specification outputted by this library together with\n`swagger-codegen <https://github.com/swagger-api/swagger-codegen>`_ to generate client code in your language of choice:\n\n.. code:: console\n\n $ docker run --rm -v ${PWD}:/local swaggerapi/swagger-codegen-cli generate -i /local/tests/reference.yaml -l javascript -o /local/.codegen/js\n\nSee the GitHub page linked above for more details.\n\n.. _readme-testproj:\n\n6. Example project\n==================\n\nFor additional usage examples, you can take a look at the test project in the ``testproj`` directory:\n\n.. code:: console\n\n $ git clone https://github.com/axnsan12/drf-yasg.git\n $ cd drf-yasg\n $ virtualenv venv\n $ source venv/bin/activate\n (venv) $ cd testproj\n (venv) $ python -m pip install --upgrade pip setuptools\n (venv) $ pip install --upgrade -r requirements.txt\n (venv) $ python manage.py migrate\n (venv) $ python manage.py runserver\n (venv) $ firefox localhost:8000/swagger/\n\n************************\nThird-party integrations\n************************\n\ndjangorestframework-camel-case\n===============================\n\nIntegration with `djangorestframework-camel-case <https://github.com/vbabiy/djangorestframework-camel-case>`_ is\nprovided out of the box - if you have ``djangorestframework-camel-case`` installed and your ``APIView`` uses\n``CamelCaseJSONParser`` or ``CamelCaseJSONRenderer``, all property names will be converted to *camelCase* by default.\n\ndjangorestframework-recursive\n===============================\n\nIntegration with `djangorestframework-recursive <https://github.com/heywbj/django-rest-framework-recursive>`_ is\nprovided out of the box - if you have ``djangorestframework-recursive`` installed.\n\n.. |actions| image:: https://img.shields.io/github/actions/workflow/status/axnsan12/drf-yasg/review.yml?branch=master\n :target: https://github.com/axnsan12/drf-yasg/actions\n :alt: GitHub Workflow Status\n\n.. |codecov| image:: https://img.shields.io/codecov/c/github/axnsan12/drf-yasg/master.svg\n :target: https://codecov.io/gh/axnsan12/drf-yasg\n :alt: Codecov\n\n.. |pypi-version| image:: https://img.shields.io/pypi/v/drf-yasg.svg\n :target: https://pypi.org/project/drf-yasg/\n :alt: PyPI\n\n.. |gitter| image:: https://badges.gitter.im/drf-yasg.svg\n :target: https://app.gitter.im/#/room/#drf-yasg:gitter.im\n :alt: Gitter\n\n.. |rtd-badge| image:: https://img.shields.io/readthedocs/drf-yasg.svg\n :target: https://drf-yasg.readthedocs.io/\n :alt: ReadTheDocs\n\n.. |heroku-button| image:: https://www.herokucdn.com/deploy/button.svg\n :target: https://heroku.com/deploy?template=https://github.com/axnsan12/drf-yasg\n :alt: Heroku deploy button\n\n.. |nbsp| unicode:: 0xA0\n :trim:\n\ndrf-extra-fields\n=================\n\nIntegration with `drf-extra-fields <https://github.com/Hipo/drf-extra-fields>`_ has a problem with Base64 fields.\nThe drf-yasg will generate Base64 file or image fields as Readonly and not required. Here is a workaround code\nfor display the Base64 fields correctly.\n\n.. code:: python\n\n class PDFBase64FileField(Base64FileField):\n ALLOWED_TYPES = ['pdf']\n\n class Meta:\n swagger_schema_fields = {\n 'type': 'string',\n 'title': 'File Content',\n 'description': 'Content of the file base64 encoded',\n 'read_only': False # <-- FIX\n }\n\n def get_file_extension(self, filename, decoded_file):\n try:\n PyPDF2.PdfFileReader(io.BytesIO(decoded_file))\n except PyPDF2.utils.PdfReadError as e:\n logger.warning(e)\n else:\n return 'pdf'\n",
"bugtrack_url": null,
"license": "BSD License",
"summary": "Automated generation of real Swagger/OpenAPI 2.0 schemas from Django Rest Framework code.",
"version": "1.21.10.post1",
"project_urls": {
"Homepage": "https://github.com/axnsan12/drf-yasg"
},
"split_keywords": [
"drf",
"django",
"django-rest-framework",
"schema",
"swagger",
"openapi",
"codegen",
"swagger-codegen",
"documentation",
"drf-yasg",
"django-rest-swagger",
"drf-openapi"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c197dde1ba4ffc9923c9d97069c76d0469eb17b886513cdd6380a21e4290134d",
"md5": "2c9f2678f0aad69b9f460c4265b0661d",
"sha256": "aa6fdd504b727bcc6ef8c05540505b8c53922156058cf64da269cd90bdeed2d8"
},
"downloads": -1,
"filename": "humansignal_drf_yasg-1.21.10.post1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2c9f2678f0aad69b9f460c4265b0661d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 4289795,
"upload_time": "2024-11-12T16:44:29",
"upload_time_iso_8601": "2024-11-12T16:44:29.311318Z",
"url": "https://files.pythonhosted.org/packages/c1/97/dde1ba4ffc9923c9d97069c76d0469eb17b886513cdd6380a21e4290134d/humansignal_drf_yasg-1.21.10.post1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9af9959d67a97b984ac63596444625ba7e318b5567be57007592d3439f9a502f",
"md5": "d493b2d22d9a06843e3e603f99d6fa99",
"sha256": "ed3cd9c6b305578e8f92afb05e229b1de39aa2da5b3737faf61ec066a1e7cbb4"
},
"downloads": -1,
"filename": "humansignal-drf-yasg-1.21.10.post1.tar.gz",
"has_sig": false,
"md5_digest": "d493b2d22d9a06843e3e603f99d6fa99",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 4513155,
"upload_time": "2024-11-12T16:44:35",
"upload_time_iso_8601": "2024-11-12T16:44:35.346325Z",
"url": "https://files.pythonhosted.org/packages/9a/f9/959d67a97b984ac63596444625ba7e318b5567be57007592d3439f9a502f/humansignal-drf-yasg-1.21.10.post1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-12 16:44:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "axnsan12",
"github_project": "drf-yasg",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "humansignal-drf-yasg"
}
JSON
