An adapter to use swagger-ui with django-tastypie
JavaScript CSS Python
Switch branches/tags
Pull request Compare This branch is 79 commits behind concentricsky:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



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


Install package:

pip install django-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.

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.


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.


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

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.