django-tastypie-swagger is a small adapter library to construct Swagger documentation from Tastypie resources.
This package provides two things:
- An embedded instance of Swagger UI to point a URL to.
- Automatic Resource Listing and API Declaration generation that is consumed by #1
pip install django-tastypie-swagger-ng
git clone https://github.com/ifanrx/django-tastypie-swagger.git
pip install -e django-tastypie-swagger
Add to INSTALLED_APPS:
INSTALLED_APPS = [
...
'tastypie_swagger',
...
]
Define TASTYPIE_SWAGGER_API_MODULE_LIST in your settings:
TASTYPIE_SWAGGER_API_MODULE_LIST = (
{'path': 'app_name.path',
'obj': 'xxx',
'func_name': 'xxx'},
{'path': 'app_name.path',
'obj': 'xxx',
'func_name': 'xxx'}
)
TASTYPIE_SWAGGER_API_MODULE_LIST is an iterable object. Each item is a dict.
- path: It should be a python path can find your api instance, like polls.api(polls is your APP's name, there is a api.py in directory polls)
- obj: It should be an Api instance or an instance who have a function to get an Api instance
- func_name: if isinstance(obj, Api) is True, func_name should be ''
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.
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. Ifresource_type
is ommitted and thehttp_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.
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.
https://github.com/swagger-api/swagger-ui/tree/v3.17.0
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md