apiref - Automatically generate OpenAPI/Swagger spec

apiref is a library that makes it easy to document your API endpoints using simple decorators.

Install

$ pip install apiref

Example

Dev setup

Initialize local repository

$ pipenv install -d                     # Install all dependencies
$ pipenv run python setup.py develop    # Setup the pkg for local development
$ pipenv shell                          # Open shell within the virtualenv

Available commands

$ peltak --help     # Show the list of available commands
$ peltak test       # Run tests
$ peltak check      # Run code checks
$ peltak docs       # Build documentation using Sphinx

Documentation

exception apiref.Error

Base class for all apiref exceptions.

apiref.payload(schema: Optional[marshmallow.schema.Schema] = None, description: str = '', positional: bool = False, converter=None)

Define an API route accepted payload.

This is what is passed in the request body.

Example

>>> import apiref
>>> import apiref.ext
>>> from marshmallow import Schema, fields
>>>
>>> apiref.ext.set_payload_loader(lambda *a, **kw: {'value': '123'})
>>>
>>> class FakeSchema(Schema):
...     value = fields.Str()
>>>
>>>
>>> def get_payload(*args, **kw):
...     return {'value': '123'}
>>>
>>>
>>> @apiref.payload(FakeSchema())
... def fake_route(payload):
...     return payload
>>>
>>>
>>> fake_route()
{'value': '123'}
>>> apiref.ext.set_payload_loader(None)

apiref.response(status, schema=None, description='')

Define a single response for the given handler.

You can define multiple responses for the given handler by using this decorator multiple times.

apiref.result(code: int = 200, schema: Optional[marshmallow.schema.Schema] = None, description: str = '')

Define the schema for the main route value.

This will be used both to generate the OpenAPI spec as well as to marshall the actual function return value with the schema provided.

Example

>>> import apiref
>>> import apiref.ext
>>> from marshmallow import Schema, fields
>>>
>>> apiref.ext.set_response_builder(apiref.ext.dummy_response_builder)
>>>
>>> class SimpleSchema(Schema):
...     value = fields.Str()
>>>
>>> @apiref.result(201, SimpleSchema())
... def fake_route():
...     return {'value': 123}
>>>
>>> fake_route()
({'value': '123'}, 201)
>>> apiref.ext.set_response_builder(None)

apiref.schema_name(schema: marshmallow.schema.Schema) → str

Return schema name from schema class.

apiref.spec_for_route(view_fn)

Generate OpenAPI/Swagger spec from the given view function*.

Route meta is generated by the decorators and saved on the view function. This function can be used to generate an OpenAPI spec out of that meta object.

Example

>>> import apiref
>>> from marshmallow import Schema, fields
>>>
>>> class FakeSchema(Schema):
...     value = fields.Int()
>>>
>>>
>>> @apiref.payload(FakeSchema())
... @apiref.result(200, FakeSchema(), "Fake result")
... def fake_route(payload) -> Dict[str, Any]:
...     ''' Fake endpoint for testing. '''
...     return {'value': '32'}
>>>
>>>
>>> spec, schemas = apiref.spec_for_route(fake_route)
>>>
>>> spec['summary']
'Fake endpoint for testing.'
>>> spec['requestBody'].keys()
dict_keys(['description', 'content'])
>>> spec['requestBody']['content']
{'application/json': {'schema': 'FakeSchema'}}
>>> spec['responses'][200]['description']
'Fake result'
>>> spec['responses'][200]['content']
{'application/json': {'schema': 'FakeSchema'}}

apiref.tags(*tags: str)

Add tags to route reference docs.