a demo of flasgger. https://github.com/rochacbruno/flasgger

flasgger-demo.py

from flask import Flask, jsonify
from flask import request
from flasgger import Swagger, SwaggerView, Schema, fields
from flasgger import APISpec
from flasgger.utils import apispec_to_template


class Color(Schema):
    name = fields.Str()
    code = fields.Str()


class Palette(Schema):
    pallete_name = fields.Str()
    colors = fields.Nested(Color, many=True)


class CategorySchema(Schema):
    id = fields.Int()
    name = fields.Str(required=True)


class PetSchema(Schema):
    category = fields.Nested(CategorySchema, many=True)
    name = fields.Str()


class PaletteView(SwaggerView):
    parameters = [
        {
            "name": "palette",
            "in": "path",
            "type": "string",
            "enum": ["all", "rgb", "cmyk"],
            "required": True,
            "default": "all"
        }
    ]
    responses = {
        200: {
            "description": "A list of colors (may be filtered by palette)",
            "schema": Palette
        }
    }

    def get(self, palette):
        """
        Colors API using schema
        This example is using marshmallow schemas
        """
        all_colors = {
            'cmyk': ['cian', 'magenta', 'yellow', 'black'],
            'rgb': ['red', 'green', 'blue']
        }
        if palette == 'all':
            result = all_colors
        else:
            result = {palette: all_colors.get(palette)}
        return jsonify(result)


app = Flask(__name__)

spec = APISpec(
    title='Flasger Petstore',
    version='1.0.10',
    plugins=[
        'apispec.ext.flask',
        'apispec.ext.marshmallow',
    ],
)

# template = spec.to_flasgger(
#    app,
#    definitions=[CategorySchema, PetSchema],
#    paths=[random_pet]
# )


@app.route('/random/<palette>')
def random_color(palette):
    """Example endpoint returning a list of colors by palette
    This is using docstrings for specifications.
    ---
    parameters:
      - name: palette
        in: path
        type: string
        enum: ['all', 'rgb', 'cmyk']
        required: true
        default: all
    definitions:
      Palette:
        type: object
        properties:
          palette_name:
            type: array
            items:
              $ref: '#/definitions/Color'
      Color:
        type: string
    responses:
      200:
        description: A list of colors (may be filtered by palette)
        schema:
          $ref: '#/definitions/Palette'
        examples:
          rgb: ['red', 'green', 'blue']
    """
    all_colors = {
        'cmyk': ['cian', 'magenta', 'yellow', 'black'],
        'rgb': ['red', 'green', 'blue']
    }
    if palette == 'all':
        result = all_colors
    else:
        result = {palette: all_colors.get(palette)}

    return jsonify(result)


@app.route('/pet', methods=['POST'])
def create_pet():
    """
    Create pet.
    ---
    parameters:
      - name: body
        in: body
        required: true
        schema:
          $ref: '#/definitions/Pet'

    responses:
      200:
        description: A single user item
        schema:
          $ref: '#/definitions/Pet'
    """
    return jsonify(request.get_json())


app.add_url_rule(
    '/colors/<palette>',
    view_func=PaletteView.as_view('colors'),
    methods=['GET']
)

template = apispec_to_template(
    app=app,
    spec=spec,
    definitions=[Color, Palette, PetSchema],
    paths=app.view_functions.values()
)

print app.view_functions
print apispec_to_template.__doc__


swagger = Swagger(app, template=template)

app.run(host='0.0.0.0', port=5000, debug=True)