Tree @master (Download .tar.gz)
apispec
A pluggable API specification generator. Currently supports the OpenAPI Specification (f.k.a. the Swagger specification).
Features
- Supports the OpenAPI Specification (versions 2 and 3)
- Framework-agnostic
- Built-in support for marshmallow
- Utilities for parsing docstrings
Example Application
from apispec import APISpec from apispec.ext.marshmallow import MarshmallowPlugin from apispec_webframeworks.flask import FlaskPlugin from flask import Flask from marshmallow import Schema, fields # Create an APISpec spec = APISpec( title="Swagger Petstore", version="1.0.0", openapi_version="3.0.2", plugins=[FlaskPlugin(), MarshmallowPlugin()], ) # Optional marshmallow support class CategorySchema(Schema): id = fields.Int() name = fields.Str(required=True) class PetSchema(Schema): category = fields.List(fields.Nested(CategorySchema)) 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: content: application/json: schema: PetSchema """ pet = get_random_pet() return PetSchema().dump(pet) # Register the path and the entities within it with app.test_request_context(): spec.path(view=random_pet)
Generated OpenAPI Spec
import json print(json.dumps(spec.to_dict(), indent=2)) # { # "paths": { # "/random": { # "get": { # "description": "Get a random pet", # "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" # } # } # } # } # } # } # } 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 # 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'} # tags: []
Documentation
Documentation is available at https://apispec.readthedocs.io/ .
Ecosystem
A list of apispec-related libraries can be found at the GitHub wiki here:
Support apispec
apispec is maintained by a group of volunteers. If you'd like to support the future of the project, please consider contributing to our Open Collective:
Professional Support
Professionally-supported apispec is available through the Tidelift 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]
Security Contact Information
To report a security vulnerability, please use the Tidelift security contact. Tidelift will coordinate the fix and disclosure.
Project Links
- Docs: https://apispec.readthedocs.io/
- Changelog: https://apispec.readthedocs.io/en/latest/changelog.html
- Contributing Guidelines: https://apispec.readthedocs.io/en/latest/contributing.html
- PyPI: https://pypi.python.org/pypi/apispec
- Issues: https://github.com/marshmallow-code/apispec/issues
License
MIT licensed. See the bundled LICENSE file for more details.
Commit History @master
- Remove template comment and switch spaces to tabs Ben Wilson 2 years ago
- Update standards version to 4.5.1, no changes needed. Kali Janitor 2 years ago
- Wrap long lines in changelog entries: 3.3.1-0kali2. Kali Janitor 3 years ago
- Prepare for Release Sophie Brun 3 years ago
- debian/rules: fix for pytest version 6 Sophie Brun 3 years ago
- Set upstream metadata fields: Bug-Database, Bug-Submit, Repository, Repository-Browse. Kali Janitor 3 years ago
- Add GitLab's CI configuration file Sophie Brun 3 years ago
- Configure git-buildpackage for Kali Sophie Brun 3 years ago
- Initial release Sophie Brun 3 years ago
- New upstream version 3.3.1 Sophie Brun 3 years ago