djsw_wrapper

Missing Swagger and Django tool.

What?

Swagger/OpenAPI is an amazing thing. It allows you to describe your schema completely in yaml/json and have a number of backends which allow you to generate code for many frameworks and languages. Unfortunately, there were no options to use Swagger as a schema source if you develop your code using Django/DRF (however, the latter can generate Swagger schema from your current source). Until now!

Requirements

django, djangorestframework, jinja2, flex

Okay, how do I shoot the web Swagger?

• Get this package: pip install djsw_wrapper
• Modify your django project's settings.py:

...
# Application definition

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'rest_framework',
    'djsw_wrapper', # << add this
    'stubapp.apps.StubappConfig'
]

# This: full path to schema resource (local file or url, json or yaml)
SWAGGER_SCHEMA = '/path/to/swagger/schema'

# And this (optional, but recommended):
SWAGGER_MODULE = 'swagger_controller_python_module_name'

• Add new url patterns to urls.py:

from djsw_wrapper.router import SwaggerRouter

router = SwaggerRouter()

urlpatterns = router.get_urls() + [
            # ^^^^^^^^^^^^^^^^^^^ add this
    url(r'^admin/', admin.site.urls)
]

• Basically, you're all set now. However, if you don't have any controllers (views in Django's terminology), you can generate code for them (need SWAGGER_MODULE setting populated):

$ python manage.py makeswaggerviews

• Go!

$ python manage.py runserver

How does it work?

1. Schema parsing and route generation

It parses swagger schema and creates url patterns for each path described there. Next, each path is bound to the corresponding view (controller in Swagger's terminology). How this bounding happens? Firstly, it tries to import SWAGGER_MODULE module, specified in settings.py. If there's no such module or setting, stub handlers are autogenerated in runtime. If there is a module, tool looks into x-swagger-router-controller property in each path definition; if property is present and points to callable view in aforementioned SWAGGER_MODULE module, bounding happens. If not, stub is used.

2. Request processing

When request comes to a certain endpoint (path) and there's a suitable handler (view) for it, validation and serialization happens automatically. For example, if you specified some parameter for a path as required and it's not present in the request, client will get an error message. The same happens if there's type inconsistency (for example, you specified integer, but client sent string). If all is good, suitable handler (view) is executed (or stub handler, if bounding didn't happen).