Skip to main content

A pluggable API specification generator. Currently supports the OpenAPI specification (f.k.a. Swagger 2.0).

Project description

Latest version https://travis-ci.org/marshmallow-code/apispec.svg?branch=dev Documentation

A pluggable API specification generator. Currently supports the OpenAPI specification (f.k.a. Swagger 2.0).

Features

  • Supports OpenAPI 2.0 specification (f.k.a. Swagger)

  • Framework-agnostic

  • Includes plugins for marshmallow, Flask, Tornado, and bottle.

  • Utilities for parsing docstrings

Example Application

from apispec import APISpec
from flask import Flask, jsonify
from marshmallow import Schema, fields

# Create an APISpec
spec = APISpec(
    title='Swagger Petstore',
    version='1.0.0',
    plugins=[
        'apispec.ext.flask',
        'apispec.ext.marshmallow',
    ],
)

# Optional marshmallow support
class CategorySchema(Schema):
    id = fields.Int()
    name = fields.Str(required=True)

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

# Optional Flask support
app = Flask(__name__)

@app.route('/random')
def random_pet():
    """A cute furry animal endpoint.
    ---
    get:
        description: Get a random pet
        responses:
            200:
                description: A pet to be returned
                schema: PetSchema
    """
    pet = get_random_pet()
    return jsonify(PetSchema().dump(pet).data)

# Register entities and paths
spec.definition('Category', schema=CategorySchema)
spec.definition('Pet', schema=PetSchema)
with app.test_request_context():
    spec.add_path(view=random_pet)

Generated OpenAPI Spec

spec.to_dict()
# {
#   "info": {
#     "title": "Swagger Petstore",
#     "version": "1.0.0"
#   },
#   "swagger": "2.0",
#   "paths": {
#     "/random": {
#       "get": {
#         "description": "A cute furry animal endpoint.",
#         "responses": {
#           "200": {
#             "schema": {
#               "$ref": "#/definitions/Pet"
#             },
#             "description": "A pet to be returned"
#           }
#         },
#       }
#     }
#   },
#   "definitions": {
#     "Pet": {
#       "properties": {
#         "category": {
#           "type": "array",
#           "items": {
#             "$ref": "#/definitions/Category"
#           }
#         },
#         "name": {
#           "type": "string"
#         }
#       }
#     },
#     "Category": {
#       "required": [
#         "name"
#       ],
#       "properties": {
#         "name": {
#           "type": "string"
#         },
#         "id": {
#           "type": "integer",
#           "format": "int32"
#         }
#       }
#     }
#   },
# }

Documentation

Documentation is available at http://apispec.readthedocs.io/ .

Ecosystem

A list of apispec-related libraries can be found at the GitHub wiki here:

https://github.com/marshmallow-code/apispec/wiki/Ecosystem

License

MIT licensed. See the bundled LICENSE file for more details.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page