marshmallow-code/apispecPublic

NotificationsYou must be signed in to change notification settings
Fork185
Star1.2k

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

License

MIT license

1.2k stars 185 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 1,799 Commits
.github		.github
docs		docs
src/apispec		src/apispec
tests		tests
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
AUTHORS.rst		AUTHORS.rst
CHANGELOG.rst		CHANGELOG.rst
CONTRIBUTING.rst		CONTRIBUTING.rst
LICENSE		LICENSE
README.rst		README.rst
RELEASING.md		RELEASING.md
SECURITY.md		SECURITY.md
pyproject.toml		pyproject.toml
readthedocs.yml		readthedocs.yml
tox.ini		tox.ini

Repository files navigation

apispec

A pluggable API specification generator. Currently supports theOpenAPI Specification (f.k.a. the Swagger specification).

Features

Supports the OpenAPI Specification (versions 2 and 3)
Framework-agnostic
Built-in support formarshmallow
Utilities for parsing docstrings

Installation

$ pip install -U apispec

When using the marshmallow plugin, ensure a compatible marshmallow version is used:

$ pip install -U apispec[marshmallow]

Example Application

fromapispecimportAPISpecfromapispec.ext.marshmallowimportMarshmallowPluginfromapispec_webframeworks.flaskimportFlaskPluginfromflaskimportFlaskfrommarshmallowimportSchema,fields# Create an APISpecspec=APISpec(title="Swagger Petstore",version="1.0.0",openapi_version="3.0.2",plugins=[FlaskPlugin(),MarshmallowPlugin()],)# Optional marshmallow supportclassCategorySchema(Schema):id=fields.Int()name=fields.Str(required=True)classPetSchema(Schema):category=fields.List(fields.Nested(CategorySchema))name=fields.Str()# Optional security scheme supportapi_key_scheme= {"type":"apiKey","in":"header","name":"X-API-Key"}spec.components.security_scheme("ApiKeyAuth",api_key_scheme)# Optional Flask supportapp=Flask(__name__)@app.route("/random")defrandom_pet():"""A cute furry animal endpoint.    ---    get:      description: Get a random pet      security:        - ApiKeyAuth: []      responses:        200:          content:            application/json:              schema: PetSchema    """pet=get_random_pet()returnPetSchema().dump(pet)# Register the path and the entities within itwithapp.test_request_context():spec.path(view=random_pet)

Generated OpenAPI Spec

importjsonprint(json.dumps(spec.to_dict(),indent=2))# {#   "paths": {#     "/random": {#       "get": {#         "description": "Get a random pet",#         "security": [#           {#             "ApiKeyAuth": []#           }#         ],#         "responses": {#           "200": {#             "content": {#               "application/json": {#                 "schema": {#                   "$ref": "#/components/schemas/Pet"#                 }#               }#             }#           }#         }#       }#     }#   },#   "tags": [],#   "info": {#     "title": "Swagger Petstore",#     "version": "1.0.0"#   },#   "openapi": "3.0.2",#   "components": {#     "parameters": {},#     "responses": {},#     "schemas": {#       "Category": {#         "type": "object",#         "properties": {#           "name": {#             "type": "string"#           },#           "id": {#             "type": "integer",#             "format": "int32"#           }#         },#         "required": [#           "name"#         ]#       },#       "Pet": {#         "type": "object",#         "properties": {#           "name": {#             "type": "string"#           },#           "category": {#             "type": "array",#             "items": {#               "$ref": "#/components/schemas/Category"#             }#           }#         }#       }#       "securitySchemes": {#          "ApiKeyAuth": {#            "type": "apiKey",#            "in": "header",#            "name": "X-API-Key"#         }#       }#     }#   }# }print(spec.to_yaml())# components:#   parameters: {}#   responses: {}#   schemas:#     Category:#       properties:#         id: {format: int32, type: integer}#         name: {type: string}#       required: [name]#       type: object#     Pet:#       properties:#         category:#           items: {$ref: '#/components/schemas/Category'}#           type: array#         name: {type: string}#       type: object#   securitySchemes:#     ApiKeyAuth:#       in: header#       name: X-API-KEY#       type: apiKey# info: {title: Swagger Petstore, version: 1.0.0}# openapi: 3.0.2# paths:#   /random:#     get:#       description: Get a random pet#       responses:#         200:#           content:#             application/json:#               schema: {$ref: '#/components/schemas/Pet'}#       security:#       - ApiKeyAuth: []# tags: []

Documentation

Documentation is available athttps://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

Support apispec

apispec is maintained by a group ofvolunteers.If you'd like to support the future of the project, please considercontributing to our Open Collective:

Professional Support

Professionally-supported apispec is available through theTidelift Subscription.

Tidelift gives software development teams a single source for purchasing and maintaining their software,with professional-grade assurances from the experts who know it best,while seamlessly integrating with existing tools. [Get professional support]