poc.py

from smore.apispec import APISpec

spec = APISpec(
    title='Swagger Petstore',
    version='1.0.0',
    description='This is a sample server Petstore server.  You can find out more '
    'about Swagger at <a href=\"http://swagger.wordnik.com\">http://swagger.wordnik.com</a> '
    'or on irc.freenode.net, #swagger.  For this sample, you can use the api '
    'key \"special-key\" to test the authorization filters',
    plugins=[
        'smore.ext.marshmallow',
        'smore.ext.flask',
        #...
    ]
)

# with no plugins

spec.definition('Pet',
    properties={
        'id': {'type': 'integer', 'format': 'int64'},
        'category': spec.ref('Category'),
        'name': {'type': 'string', 'example': 'doggie'},
        'photoUrls': {'type': 'array', 'items': {'type': 'string'}},
        'tags': {'type': 'array', 'items': spec.ref('Tag')}
    },
    enum=['name', 'photoUrls']
)

spec.definition('Category')  # ...
spec.definition('Tag')  # ...

@spec.path('GET', '/pet/{petId}',
    parameters=[{
        "required": True, "format": "int64", "name": "petId", "in": "path", "type": "integer",
        "description": "ID of pet that needs to be fetched"
    }],
    responses={
        200: {'schema': spec.ref('Pet'), 'description': 'successful operation'},
        400: {'description': 'Invalid ID supplied'},
        404: {'description': 'Pet not found'},
    },
    produces=['application/json', 'application/xml']
)
def get_pet(petId):
    return 'representation of pet {}...'.format(petId)

# with marshmallow plugin, can pass Schema to autogenerate definitions

spec.load_plugin('smore.ext.marshmallow')

spec.definition('Pet', schema=PetSchema)

# can also generate swagger parameters from Schemas

@spec.path('GET', '/pet/{petId}',
        parameters=schema2params(GETSchema),
        responses={
            200: {'schema': spec.ref('Pet')}
        }
)
def get_pet_id(petId):
    return '...'

# with webargs plugin, can pass wargs to autogenerate parameter objects
spec.load_plugin('smore.ext.webargs')

from webargs import Arg

args = {
    'petId': Arg(int, description='ID of pet that needs to be fetched'),
}

@spec.path('GET', '/pet/{petId}', wargs=args, responses=..., produces=[...])
def get_pet_generic(petId):
    return 'representation of {}'.format(petId)


# with flask plugin enabled, no need to put in path and method

spec.load_plugin('smore.ext.flask')

@spec.path(wargs=args, responses=..., produces=[...])
@app.route('/pet/<int:petId>/')
def get_pet_flask(petId):
    return 'representation of {}'.format(petId)


# can also pull from app's config values, e.g.
# app.config['DEFAULT_CONTENT_TYPES'] = ['application/json', 'application/xml']


# Programmatic API

spec.add_path(get_pet_flask, wargs=args, responses=..., produces=[])


# Marshmallow plugin example

def definition_from_schema(name, schema, **kwargs):
    return {
        name: smore.swagger.schema2definition(schema)
    }

def setup(spec):
    spec.register_definition_helper(definition_from_schema)


# APISpec
from collections import OrderedDict

class APISpec(object):

    def __init__(self, title, description, ..., plugins):
        # ...
        self._definition_helpers = OrderedDict()
        #..
        for plugin_path in plugins:
            plugin = self.load_plugin(plugin_path)
            plugin.setup(self)
        #...

    def register_definition_helper(self, func, name=None):
        name = name or func.__name__
        self._definition_helpers[name] = func


    def definition(self, name, **kwargs):
        ret = {}
        for name, func in self._definition_helpers.items():
            ret.update(func(name, **kwargs))
        return ret

    # ...