A pluggable API documentation generator. Currently supports the Swagger 2.0 specification.
Project description
A pluggable API documentation generator. Currently supports the Swagger 2.0 specification.
Features
Supports Swagger 2.0
Framework-agnostic
Includes plugins for marshmallow and Flask
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',
description='A sample Petstore API.',
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)
ctx = app.test_request_context()
ctx.push()
# Register entities and paths
spec.definition('Category', schema=CategorySchema)
spec.definition('Pet', schema=PetSchema)
spec.add_path(view=random_pet)Generated Swagger Spec
spec.to_dict()
# {
# "info": {
# "title": "Swagger Petstore",
# "version": "1.0.0"
# },
# "swagger": "2.0",
# "description": "A sample Petstore API."
# "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.org/ .
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-0.4.1.tar.gz
(25.6 kB
view details)
Built Distribution
File details
Details for the file apispec-0.4.1.tar.gz.
File metadata
- Download URL: apispec-0.4.1.tar.gz
- Upload date:
- Size: 25.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 1b690e5b461677c9938bb3341f2baab8c475d1371dedcbbcd5a23a58b802ee4c |
|
| MD5 | 8f212d5a5e6738ee13be136d66c444f3 |
|
| BLAKE2b-256 | c54c18e392ba4f97f48b83ef4ad862adb584c4881c0a71a832e35bbd5e5f57a7 |
Provenance
File details
Details for the file apispec-0.4.1-py2.py3-none-any.whl.
File metadata
- Download URL: apispec-0.4.1-py2.py3-none-any.whl
- Upload date:
- Size: 16.2 kB
- Tags: Python 2, Python 3
- Uploaded using Trusted Publishing? No
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | f1c8eb19c24fde1f0769b6a7ee9fe5e7aa59bedaaa5691c352458c78f771cbb2 |
|
| MD5 | 1c716f64846ff7ee66e0a7c7336c3d0d |
|
| BLAKE2b-256 | 0c590fc3505b56eeee98beb4b99dd750cdf44df70ab58bef2ca5354d6d072354 |
