An adapter to use swagger-ui with django-tastypie
Project description
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
=====
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 payhon 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 <http://django-tastypie.readthedocs.org/en/latest/cookbook.html#adding-search-functionality>`_)
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 <https://gist.github.com/4041352>`_ as a workaround to this issue.
.. _Swagger: http://swagger.wordnik.com/
.. _Tastypie: https://django-tastypie.readthedocs.org
.. _Resource Listing: https://github.com/wordnik/swagger-core/wiki/Resource-Listing
.. _API Declaration: https://github.com/wordnik/swagger-core/wiki/API-Declaration
.. _Swagger UI: https://github.com/wordnik/swagger-ui
.. _tastypie.api.Api: https://django-tastypie.readthedocs.org/en/latest/api.html
.. _Joshua Kehn: mailto:josh@kehn.us
========
**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
=====
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 payhon 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 <http://django-tastypie.readthedocs.org/en/latest/cookbook.html#adding-search-functionality>`_)
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 <https://gist.github.com/4041352>`_ as a workaround to this issue.
.. _Swagger: http://swagger.wordnik.com/
.. _Tastypie: https://django-tastypie.readthedocs.org
.. _Resource Listing: https://github.com/wordnik/swagger-core/wiki/Resource-Listing
.. _API Declaration: https://github.com/wordnik/swagger-core/wiki/API-Declaration
.. _Swagger UI: https://github.com/wordnik/swagger-ui
.. _tastypie.api.Api: https://django-tastypie.readthedocs.org/en/latest/api.html
.. _Joshua Kehn: mailto:josh@kehn.us
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Close
Hashes for django-tastypie-swagger-ng-0.1.3.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4fd1f7dea6e8425c57700bc7038a508c7526d98bb267b9090c8fa5e292a561fe |
|
MD5 | 1c1c8440a68f2d41aeac2a071821058a |
|
BLAKE2b-256 | b7ed7c75437fd8301fdd43cc15c1aec87b9a8768f2b9215a3d7cf74ee6c95f8d |