bnotions / django-rest-swagger

Django REST Swagger

####An API documentation generator for Swagger UI and Django REST Framework version 2.3.5

For older versions of Django REST Framework, see Django REST Framework Docs

Installation

From PyPI: pip install django-rest-swagger

From source:

• Download the source
• Extract files
• Run python setup.py install

Requirements

This application was developed and tested on:

• Django 1.5.1
• Django REST Framework 2.3.4, 2.3.5

Backwards compatibility for earlier Django & Django REST Framework versions will be added in a future release. Meanwhile, please use Django REST Framework Docs to document your projects.

Quick start

Note: This application will not work with Django REST Framework < 2.3

1. Add rest_framework_swagger to your INSTALLED_APPS setting like this:

       INSTALLED_APPS = (
           ...
           'rest_framework_swagger',
       )

2. Include the rest_framework_swagger URLs to a path of your choice

   patterns = ('',
       ...
       url(r'^api-docs/', include('rest_framework_swagger.urls')),
   )

Configuration

Further configuration can optionally be made from your project's settings.py.

• Exclude namespaces: you may wish to exclude a set of URLs from documentation. By default, all views that are subclassed from Django REST Framework APIView will be included for documentation
• API Version: your API's version. Default is blank.
• Enabled methods: You may specify the methods that can be interacted with in the UI
• API key: you can specify a key for your API. Default is blank

SWAGGER_SETTINGS = {
    "exclude_namespaces": [], # List URL namespaces to ignore
    "api_version": '0.1', # Specify your API's version
    "enabled_methods": [ # Specify which methods to enable in Swagger UI
        'get',
        'post',
        'put',
        'patch',
        'delete'
    ],
    "api_key": '', # An API key
}

How It Works

This project is built on the Django REST Framework Docs and uses the lovely Swagger from Wordnik as an interface. This application introspectively generates documentation based on your Django REST Framework API code. Comments are generated in combination from code analysis and comment extraction. Here are some of the features that are documented:

• API title - taken from the class name
• Methods allowed
• Serializers & fields in use by a certain method
• Field default values, minimum, maximum, read-only and required attributes
• URL parameters (ie. /product/{id})
• Query parameters (user-defined) - Custom parameters. It is possible to customize a parameter list for your API. To do so, include a key-value pair in the docstring of your API class delimited by two hyphens ('--'). Example: 'start_time -- The first reading':

    class Countries(APIView):
        """
        This text is the description for this API
        param1 -- A first parameter
        param2 -- A second parameter
        """

Example

Included in this repository is a functioning example. Please clone the repo, copy or reference the rest_framework_swagger directory into the cigar_example folder. Install the required packages using pip install -r requirements.txt

Screenshots

Bugs & Contributions

Please report bugs by opening an issue

Contributions are welcome and are encouraged !

Special Thanks

Thanks to BNOTIONS for sponsoring development time and for being an awesome place to work, play & innovate

Many thanks to Tom Christie & all the contributors who have developed Django REST Framework

Contributors

• Marc Gibbons (@marcgibbons)

Django REST Framework Docs contributors:

• Scott Mountenay (@scottmx81)
• @swistakm
• Peter Baumgartner (@ipmb)
• Marlon Bailey (@avinash240)

django-rest-swagger's Issues

Settings are not picked up by swagger

In settings.py:

SWAGGER_SETTINGS = {
    "exclude_namespaces": [],
    "api_version": '1',
    "enabled_methods": [
        'get',
        'post',
        'put',
        'patch',
        'delete'
    ],
    "is_authenticated": False
}

However version is not picked:
{"basePath": "http://192.168.211.130:8080/swagger/api-docs", "swaggerVersion": "1.2", "apiVersion": "", "apis": [{"path": "/api/auth"}, {"path": "/api/v1"}]}

The apiVersion should be '1' and it is not.
This suggests that the SWAGGER_SETTINGS is not really being picked up by swagger.