Synopsis

django-tastypie-swagger is a small adapter library to construct Swagger documentation from Tastypie resources.

This package provides two things:

1. An embedded instance of Swagger UI to point a URL to.
2. Automatic Resource Listing and API Declaration generation that is consumed by #1

Usage

Install package:

pip install django-tastypie-swagger

Add to INSTALLED_APPS:

INSTALLED_APPS = [
    ...

    'tastypie_swagger',

    ...
]

Define TASTYPIE_SWAGGER_API_MODULE in your settings. It should be a python path to your instance of tastypie.api.Api:

TASTYPIE_SWAGGER_API_MODULE = 'mainsite.urls.api'

Include in your urlconf with namespace tastypie_swagger:

urlpatterns = patterns('',
    ...

    url(r'api/doc/', include('tastypie_swagger.urls', namespace='tastypie_swagger')),

    ...
)

Swagger documentation will be served up at the URL you configured.

Configuration

The following configuration variables can be set inside settings.py to configure this application.

TASTYPIE_SWAGGER_APP_NAME

Default: 'swagger'

Changes the name of the application in the documentation view. This is also used in the title of the documentation view in the form of {{ NAME|title }} API Documentation.

TASTYPIE_SWAGGER_APP_LINK

Default: '/'

Changes where the application name is linked to in the documentation view.

TASTYPIE_SWAGGER_SHOW_DEV

Default: False

Show or hide the example documentation links.

TASTYPIE_SWAGGER_KEY_NAME

Default: 'apiKey'

Change the name of the api key that will be passed to requests.

TASTYPIE_SWAGGER_API_KEY

Default: '' (empty string)

Prefills an example api key in the documentation view.

Using extra_actions

While most ModelResource based endpoints are good as-is there are times when adding additional functionality (like search) is required. In Tastypie the recommended way do to this is by overriding the prepend_urls function and returning a list of urls that describe additional endpoints. How do you make the schema map represent these endpoints so they are properly documented?:

Add an attribute to the Meta class inside your ModelResource class called extra_actions. Following the Tastypie search example, here is how extra_actions should be defined:

class Meta:
    ...
    extra_actions = [
        {
            "name": "search",
            "http_method": "GET",
            "resource_type": "list",
            "description": "Seach endpoint",
            "fields": {
                "q": {
                    "type": "string",
                    "required": True,
                    "description": "Search query terms"
                }
            }
        }
    ]

extra_actions is a list of dictionary objects that define extra endpoints that are unavailable to introspection.

Important

extra_actions feeds directly into the schema for swagger. It does not alter the tastypie schema listing tastypie provides.

Top level keys and meaning in the extra_actions dictionary:

• name: Required. Nickname of the resource.
• http_method: Defaults to "GET". HTTP method allowed here as a string. Will be uppercased on output.
• resource_type: If this is declared as "list" then the endpoint will not include a {id} parameter in the uri or in the parameters list. This is applicable to endpoints such as the above example that filter or perform actions across many items. If resource_type is ommitted and the http_method is "GET" then the endpoint will default to "view" and include a {id} parameter in the uri and parameter list.
• description: Description of this endpoint.
• fields: Dictionary of parameters this endpoint accepts.

Field dictionaries are declared in a { "name": { [options dict] } style. This is done for compatability reasons with older versions of django-tastypie-swagger.

Warning

The structure of fields will likely change in future versions if Joshua Kehn continues committing.

Available keys and meaning for the fields dictionary.:

- ``type``: Defaults to ``"string"``. Parameter type.
- ``required``: Defaults to ``False``.
- ``description``: Defaults to ``""`` (empty string). Description of this
  parameter.

Detecting required fields

Tastypie 0.9.11 ModelResource fields do not respect the blank attribute on django model fields, which this library depends on to determine if a field is required or not.

You can use this ModelResource subclass as a workaround to this issue.