djsw_wrapper 0.2.3.0

# djsw_wrapper
Missing Swagger and Django tool.

[](https://badge.fury.io/py/djsw_wrapper)

## 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`:
```python
...
# 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`:
```python
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):
```shell
$ python manage.py makeswaggerviews
```

* Go!
```shell
$ 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).