Skip to main content

Allows to build REST API directly from Swagger schema

Project description

# djsw_wrapper
Missing Swagger and Django tool.

[![PyPI version](https://badge.fury.io/py/djsw_wrapper.svg)](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).

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

djsw_wrapper-0.2.3.0.tar.gz (12.7 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page