apispec

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

fromapispecimportAPISpecfromflaskimportFlask, jsonifyfrommarshmallowimportSchema, fields# Create an APISpecspec=APISpec(
title='Swagger Petstore',
version='1.0.0',
plugins=[
'apispec.ext.flask',
'apispec.ext.marshmallow',
],
)
# Optional marshmallow supportclassCategorySchema(Schema):
id=fields.Int()
name=fields.Str(required=True)
classPetSchema(Schema):
category=fields.Nested(CategorySchema, many=True)
name=fields.Str()
# Optional Flask supportapp=Flask(__name__)
@app.route('/random')defrandom_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()
returnjsonify(PetSchema().dump(pet).data)
ctx=app.test_request_context()
ctx.push()
# Register entities and pathsspec.definition('Category', schema=CategorySchema)
spec.definition('Pet', schema=PetSchema)
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.