Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/marshmallow-code/apispec
A pluggable API specification generator. Currently supports the OpenAPI Specification (f.k.a. the Swagger specification)..
https://github.com/marshmallow-code/apispec
api documentation flask http-api json-schema marshmallow openapi openapi-specification openapi2 openapi3 pluggable python rest-api swagger
Last synced: 1 day ago
JSON representation
A pluggable API specification generator. Currently supports the OpenAPI Specification (f.k.a. the Swagger specification)..
- Host: GitHub
- URL: https://github.com/marshmallow-code/apispec
- Owner: marshmallow-code
- License: mit
- Created: 2014-10-18T23:48:49.000Z (over 10 years ago)
- Default Branch: dev
- Last Pushed: 2025-01-07T19:29:41.000Z (19 days ago)
- Last Synced: 2025-01-14T00:05:43.770Z (13 days ago)
- Topics: api, documentation, flask, http-api, json-schema, marshmallow, openapi, openapi-specification, openapi2, openapi3, pluggable, python, rest-api, swagger
- Language: Python
- Homepage: https://apispec.readthedocs.io/
- Size: 1.9 MB
- Stars: 1,184
- Watchers: 24
- Forks: 177
- Open Issues: 30
-
Metadata Files:
- Readme: README.rst
- Changelog: CHANGELOG.rst
- Contributing: CONTRIBUTING.rst
- Funding: .github/FUNDING.yml
- License: LICENSE
- Security: SECURITY.md
- Authors: AUTHORS.rst
Awesome Lists containing this project
- starred-awesome - apispec - A pluggable API specification generator. Currently supports the OpenAPI Specification (f.k.a. the Swagger specification).. (Python)
- jimsghstars - marshmallow-code/apispec - A pluggable API specification generator. Currently supports the OpenAPI Specification (f.k.a. the Swagger specification).. (Python)
- best-of-web-python - GitHub - 10% open · ⏱️ 06.06.2024): (OpenAPI Utilities)
README
*******
apispec
*******
|pypi| |build-status| |docs| |marshmallow-support| |openapi|
.. |pypi| image:: https://badgen.net/pypi/v/apispec
:target: https://pypi.org/project/apispec/
:alt: PyPI package
.. |build-status| image:: https://github.com/marshmallow-code/apispec/actions/workflows/build-release.yml/badge.svg
:target: https://github.com/marshmallow-code/webargs/actions/workflows/build-release.yml
:alt: Build status
.. |docs| image:: https://readthedocs.org/projects/apispec/badge/
:target: https://apispec.readthedocs.io/
:alt: Documentation
.. |marshmallow-support| image:: https://badgen.net/badge/marshmallow/3,4?list=1
:target: https://marshmallow.readthedocs.io/en/latest/upgrading.html
:alt: marshmallow 3|4 compatible
.. |openapi| image:: https://badgen.net/badge/OAS/2,3?list=1&color=cyan
:target: https://github.com/OAI/OpenAPI-Specification
:alt: OpenAPI Specification 2/3 compatible
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
Installation
============
::
$ pip install -U apispec
When using the marshmallow plugin, ensure a compatible marshmallow version is used: ::
$ pip install -U apispec[marshmallow]
Example Application
===================
.. code-block:: python
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 security scheme support
api_key_scheme = {"type": "apiKey", "in": "header", "name": "X-API-Key"}
spec.components.security_scheme("ApiKeyAuth", api_key_scheme)
# Optional Flask support
app = Flask(__name__)
@app.route("/random")
def random_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()
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
----------------------
.. code-block:: python
import json
print(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 at https://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 of
`volunteers `_.
If you'd like to support the future of the project, please consider
contributing to our Open Collective:
.. image:: https://opencollective.com/marshmallow/donate/button.png
:target: https://opencollective.com/marshmallow
:width: 200
:alt: Donate to our 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`_]
.. _`Get professional support`: https://tidelift.com/subscription/pkg/pypi-apispec?utm_source=pypi-apispec&utm_medium=referral&utm_campaign=readme
.. image:: https://user-images.githubusercontent.com/2379650/45126032-50b69880-b13f-11e8-9c2c-abd16c433495.png
:target: https://tidelift.com/subscription/pkg/pypi-apispec?utm_source=pypi-apispec&utm_medium=referral&utm_campaign=readme
:alt: Get supported apispec with Tidelift
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.