A pluggable API specification generator. Currently supports the OpenAPI specification (f.k.a. the Swagger specification).
Project description
A pluggable API specification generator. Currently supports the OpenAPI Specification (f.k.a. the Swagger specification).
Features
Supports OpenAPI Specification version 2 (f.k.a. the Swagger specification) with limited support for version 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, jsonify
from marshmallow import Schema, fields
# Create an APISpec
spec = APISpec(
title='Swagger Petstore',
version='1.0.0',
openapi_version='2.0',
plugins=[
FlaskPlugin(),
MarshmallowPlugin(),
],
)
# 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.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"
# }
# }
# }
# },
# }
spec.to_yaml()
# definitions:
# Pet:
# enum: [name, photoUrls]
# properties:
# id: {format: int64, type: integer}
# name: {example: doggie, type: string}
# info: {description: 'This is a sample Petstore server. You can find out more ', title: Swagger Petstore, version: 1.0.0}
# parameters: {}
# paths: {}
# security:
# - apiKey: []
# swagger: '2.0'
# tags: []Documentation
Documentation is available at http://apispec.readthedocs.io/ .
Ecosystem
A list of apispec-related libraries can be found at the GitHub wiki here:
License
MIT licensed. See the bundled LICENSE file for more details.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
apispec-1.0.0b5.tar.gz
(49.6 kB
view details)
Built Distribution
File details
Details for the file apispec-1.0.0b5.tar.gz.
File metadata
- Download URL: apispec-1.0.0b5.tar.gz
- Upload date:
- Size: 49.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/1.12.1 pkginfo/1.4.2 requests/2.20.0 setuptools/40.5.0 requests-toolbelt/0.8.0 tqdm/4.28.1 CPython/3.6.3
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 50b1cb8f0dc12db00a53e748b27ae601efdc210f1cb4358729173337b2e47354 |
|
| MD5 | eb2b0664d36e673e5bd497b0ef572b2c |
|
| BLAKE2b-256 | 79c8e42821dbef6ecb8e7cd252047e057c77212871f1f6afe8d843d6b24a4132 |
Provenance
File details
Details for the file apispec-1.0.0b5-py2.py3-none-any.whl.
File metadata
- Download URL: apispec-1.0.0b5-py2.py3-none-any.whl
- Upload date:
- Size: 22.4 kB
- Tags: Python 2, Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/1.12.1 pkginfo/1.4.2 requests/2.20.0 setuptools/40.5.0 requests-toolbelt/0.8.0 tqdm/4.28.1 CPython/3.6.3
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 648934f67aefa386cdde5d1d38ceb1c9fe9157c59824a6fb5499409a70dabab4 |
|
| MD5 | 362f773d2b9104748c753115b268e9c3 |
|
| BLAKE2b-256 | 5d22e1c572e0d03242e5ab9d57b188ec1c6e4a4fc889dcb5da81d56f02bb1b7d |
