Document your API

Web services without a proper documentation are usually useless.

To make it easy to document your own API, WSME provides a Sphinx extension.

Install the extension

Here we consider that you already quick-started a sphinx project.

  1. In your conf.py file, add 'ext' to you extensions, and optionally set the enabled protocols.

    extensions = ['ext']
    
    wsme_protocols = ['restjson', 'restxml', 'extdirect']
    
  2. Copy toggle.js and toggle.css in your _static directory.

The wsme domain

The extension will add a new Sphinx domain providing a few directives.

Config values

wsme_protocols

A list of strings that are WSME protocol names. If provided by an additionnal package (for example WSME-Soap or WSME-ExtDirect), it must be installed.

The types and services generated documentation will include code samples for each of these protocols.

wsme_root

A string that is the full name of the service root controller. It will be used to determinate the relative path of the other controllers when they are autodocumented, and calculate the complete webpath of the other controllers.

wsme_webpath

A string that is the webpath where the wsme_root is mounted.

Directives

.. root:: <WSRoot full path>

Allow to define the service root controller in one documentation source file. To set it globally, see wsme_root.

A webpath option allow to override wsme_webpath.

Example:

.. wsme:root:: myapp.controllers.MyWSRoot
    :webpath: /api
.. service:: name/space/ServiceName

Declare a service.

.. type:: MyComplexType

Equivalent to the py:class directive to document a complex type

.. attribute:: aname

Equivalent to the py:attribute directive to document a complex type attribute. It takes an additionnal :type: field.

Example

Source Result
.. wsme:root:: wsmeext.sphinxext.SampleService
    :webpath: /api

.. wsme:type:: MyType

    .. wsme:attribute:: test

        :type: int

.. wsme:service:: name/space/SampleService

    .. wsme:function:: doit
type MyType
test
Type:int
service name/space/SampleService
function getType

Returns a MyType

Autodoc directives

Theses directives scan your code to generate the documentation from the docstrings and your API types and controllers.

.. autotype:: myapp.MyType

Generate the myapp.MyType documentation.

.. autoattribute:: myapp.MyType.aname

Generate the myapp.MyType.aname documentation.

.. autoservice:: myapp.MyService

Generate the myapp.MyService documentation.

.. autofunction:: myapp.MyService.myfunction

Generate the myapp.MyService.myfunction documentation.

Full Example

Python source

        return six.b('samplestring')
    if datatype is wsme.types.text:
        return u'sample unicode'
    if datatype is int:
        return 5
    sample_obj = getattr(datatype, 'sample', datatype)()
    return sample_obj


def get_protocols(names):
    names = list(names)
    protocols = []
    if 'rest' in names:
        names.remove('rest')
        protocols.extend('restjson', 'restxml')
    if 'restjson' in names:
        names.remove('restjson')
        protocols.append(('Json', wsme.rest.json))
    if 'restxml' in names:
        names.remove('restxml')
        protocols.append(('XML', wsme.rest.xml))
    for name in names:
        p = wsme.protocol.getprotocol(name)
        protocols.append((p.displayname or p.name, p))
    return protocols

Documentation source

.. default-domain:: wsmeext

.. autotype:: wsmeext.sphinxext.SampleType
    :members:

.. autoservice:: wsmeext.sphinxext.SampleService
    :members:

Result

type SampleType

A Sample Type

Data samples:

Json
{
    "aint": 10
}
XML
<value>
  <aint>10</aint>
</value>
SOAP
<Element 'value' at 0x3b756c0>
ExtDirect
{
    "aint": 10
}
aint
Type:int

A Int

service /
function change_aint(data, aint, dummy='useless') → SampleType
Parameters samples:
 
Json
{
    "aint": 5, 
    "data": {
        "aint": 10
    }, 
    "dummy": "samplestring"
}
XML
<parameters>
  <data>
    <aint>10</aint>
  </data>
  <aint>5</aint>
  <dummy>samplestring</dummy>
</parameters>
SOAP
N/A
ExtDirect
N/A
Return samples:
Json
{
    "aint": 10
}
XML
<result>
  <aint>10</aint>
</result>
SOAP
N/A
ExtDirect
N/A
Parameters:
  • data (SampleType) –
  • aint (int) – The new value
  • dummy (str) –
Return type:

SampleType

Returns:

The data object with its aint field value changed.

Previous topic

Integrating with a Framework

Next topic

TODO

This Page