Package: django-tastypie-swagger-ng
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 #1Usage=====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 instancefunc_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 timeswhen 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 additionalendpoints. How do you make the schema map represent these endpoints so they areproperly documented?::Add an attribute to the ``Meta`` class inside your **ModelResource** classcalled ``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 endpointsthat are unavailable to introspection... important::``extra_actions`` feeds directly into the schema **for swagger**. It doesnot 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 parameterslist. This is applicable to endpoints such as the above example that filteror perform actions across many items. If ``resource_type`` is ommitted andthe ``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 ofdjango-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 thisparameter.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