*******
apispec
*******
|pypi| |build-status| |docs| |marshmallow3| |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
.. |marshmallow3| image:: https://badgen.net/badge/marshmallow/3?list=1
:target: https://marshmallow.readthedocs.io/en/latest/upgrading.html
:alt: marshmallow 3 only
.. |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 <https://github.com/OAI/OpenAPI-Specification>`_ (f.k.a. the Swagger specification).
Features
========
- Supports the OpenAPI Specification (versions 2 and 3)
- Framework-agnostic
- Built-in support for `marshmallow <https://marshmallow.readthedocs.io/>`_
- 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 <https://apispec.readthedocs.io/en/latest/authors.html>`_.
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 <https://tidelift.com/subscription/pkg/pypi-apispec?utm_source=pypi-apispec&utm_medium=referral&utm_campaign=readme>`_.
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 <https://tidelift.com/security>`_.
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 <https://github.com/marshmallow-code/apispec/blob/dev/LICENSE>`_ file for more details.
Raw data
{
"_id": null,
"home_page": null,
"name": "apispec",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Steven Loria <sloria1@gmail.com>, J\u00e9r\u00f4me Lafr\u00e9choux <jerome@jolimont.fr>",
"keywords": "apispec, swagger, openapi, specification, oas, documentation, spec, rest, api",
"author": null,
"author_email": "Steven Loria <sloria1@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/12/66/81f6f31feafb0ee2f6c649ba33f4c768f837bbabef279f12053d00a7099d/apispec-6.8.0.tar.gz",
"platform": null,
"description": "*******\napispec\n*******\n\n|pypi| |build-status| |docs| |marshmallow3| |openapi|\n\n.. |pypi| image:: https://badgen.net/pypi/v/apispec\n :target: https://pypi.org/project/apispec/\n :alt: PyPI package\n\n.. |build-status| image:: https://github.com/marshmallow-code/apispec/actions/workflows/build-release.yml/badge.svg\n :target: https://github.com/marshmallow-code/webargs/actions/workflows/build-release.yml\n :alt: Build status\n\n.. |docs| image:: https://readthedocs.org/projects/apispec/badge/\n :target: https://apispec.readthedocs.io/\n :alt: Documentation\n\n.. |marshmallow3| image:: https://badgen.net/badge/marshmallow/3?list=1\n :target: https://marshmallow.readthedocs.io/en/latest/upgrading.html\n :alt: marshmallow 3 only\n\n.. |openapi| image:: https://badgen.net/badge/OAS/2,3?list=1&color=cyan\n :target: https://github.com/OAI/OpenAPI-Specification\n :alt: OpenAPI Specification 2/3 compatible\n\n\nA pluggable API specification generator. Currently supports the `OpenAPI Specification <https://github.com/OAI/OpenAPI-Specification>`_ (f.k.a. the Swagger specification).\n\nFeatures\n========\n\n- Supports the OpenAPI Specification (versions 2 and 3)\n- Framework-agnostic\n- Built-in support for `marshmallow <https://marshmallow.readthedocs.io/>`_\n- Utilities for parsing docstrings\n\nInstallation\n============\n\n::\n\n $ pip install -U apispec\n\nWhen using the marshmallow plugin, ensure a compatible marshmallow version is used: ::\n\n $ pip install -U apispec[marshmallow]\n\nExample Application\n===================\n\n.. code-block:: python\n\n from apispec import APISpec\n from apispec.ext.marshmallow import MarshmallowPlugin\n from apispec_webframeworks.flask import FlaskPlugin\n from flask import Flask\n from marshmallow import Schema, fields\n\n\n # Create an APISpec\n spec = APISpec(\n title=\"Swagger Petstore\",\n version=\"1.0.0\",\n openapi_version=\"3.0.2\",\n plugins=[FlaskPlugin(), MarshmallowPlugin()],\n )\n\n\n # Optional marshmallow support\n class CategorySchema(Schema):\n id = fields.Int()\n name = fields.Str(required=True)\n\n\n class PetSchema(Schema):\n category = fields.List(fields.Nested(CategorySchema))\n name = fields.Str()\n\n\n # Optional security scheme support\n api_key_scheme = {\"type\": \"apiKey\", \"in\": \"header\", \"name\": \"X-API-Key\"}\n spec.components.security_scheme(\"ApiKeyAuth\", api_key_scheme)\n\n\n # Optional Flask support\n app = Flask(__name__)\n\n\n @app.route(\"/random\")\n def random_pet():\n \"\"\"A cute furry animal endpoint.\n ---\n get:\n description: Get a random pet\n security:\n - ApiKeyAuth: []\n responses:\n 200:\n content:\n application/json:\n schema: PetSchema\n \"\"\"\n pet = get_random_pet()\n return PetSchema().dump(pet)\n\n\n # Register the path and the entities within it\n with app.test_request_context():\n spec.path(view=random_pet)\n\n\nGenerated OpenAPI Spec\n----------------------\n\n.. code-block:: python\n\n import json\n\n print(json.dumps(spec.to_dict(), indent=2))\n # {\n # \"paths\": {\n # \"/random\": {\n # \"get\": {\n # \"description\": \"Get a random pet\",\n # \"security\": [\n # {\n # \"ApiKeyAuth\": []\n # }\n # ],\n # \"responses\": {\n # \"200\": {\n # \"content\": {\n # \"application/json\": {\n # \"schema\": {\n # \"$ref\": \"#/components/schemas/Pet\"\n # }\n # }\n # }\n # }\n # }\n # }\n # }\n # },\n # \"tags\": [],\n # \"info\": {\n # \"title\": \"Swagger Petstore\",\n # \"version\": \"1.0.0\"\n # },\n # \"openapi\": \"3.0.2\",\n # \"components\": {\n # \"parameters\": {},\n # \"responses\": {},\n # \"schemas\": {\n # \"Category\": {\n # \"type\": \"object\",\n # \"properties\": {\n # \"name\": {\n # \"type\": \"string\"\n # },\n # \"id\": {\n # \"type\": \"integer\",\n # \"format\": \"int32\"\n # }\n # },\n # \"required\": [\n # \"name\"\n # ]\n # },\n # \"Pet\": {\n # \"type\": \"object\",\n # \"properties\": {\n # \"name\": {\n # \"type\": \"string\"\n # },\n # \"category\": {\n # \"type\": \"array\",\n # \"items\": {\n # \"$ref\": \"#/components/schemas/Category\"\n # }\n # }\n # }\n # }\n # \"securitySchemes\": {\n # \"ApiKeyAuth\": {\n # \"type\": \"apiKey\",\n # \"in\": \"header\",\n # \"name\": \"X-API-Key\"\n # }\n # }\n # }\n # }\n # }\n\n print(spec.to_yaml())\n # components:\n # parameters: {}\n # responses: {}\n # schemas:\n # Category:\n # properties:\n # id: {format: int32, type: integer}\n # name: {type: string}\n # required: [name]\n # type: object\n # Pet:\n # properties:\n # category:\n # items: {$ref: '#/components/schemas/Category'}\n # type: array\n # name: {type: string}\n # type: object\n # securitySchemes:\n # ApiKeyAuth:\n # in: header\n # name: X-API-KEY\n # type: apiKey\n # info: {title: Swagger Petstore, version: 1.0.0}\n # openapi: 3.0.2\n # paths:\n # /random:\n # get:\n # description: Get a random pet\n # responses:\n # 200:\n # content:\n # application/json:\n # schema: {$ref: '#/components/schemas/Pet'}\n # security:\n # - ApiKeyAuth: []\n # tags: []\n\n\nDocumentation\n=============\n\nDocumentation is available at https://apispec.readthedocs.io/ .\n\nEcosystem\n=========\n\nA list of apispec-related libraries can be found at the GitHub wiki here:\n\nhttps://github.com/marshmallow-code/apispec/wiki/Ecosystem\n\nSupport apispec\n===============\n\napispec is maintained by a group of\n`volunteers <https://apispec.readthedocs.io/en/latest/authors.html>`_.\nIf you'd like to support the future of the project, please consider\ncontributing to our Open Collective:\n\n.. image:: https://opencollective.com/marshmallow/donate/button.png\n :target: https://opencollective.com/marshmallow\n :width: 200\n :alt: Donate to our collective\n\nProfessional Support\n====================\n\nProfessionally-supported apispec is available through the\n`Tidelift Subscription <https://tidelift.com/subscription/pkg/pypi-apispec?utm_source=pypi-apispec&utm_medium=referral&utm_campaign=readme>`_.\n\nTidelift gives software development teams a single source for purchasing and maintaining their software,\nwith professional-grade assurances from the experts who know it best,\nwhile seamlessly integrating with existing tools. [`Get professional support`_]\n\n.. _`Get professional support`: https://tidelift.com/subscription/pkg/pypi-apispec?utm_source=pypi-apispec&utm_medium=referral&utm_campaign=readme\n\n.. image:: https://user-images.githubusercontent.com/2379650/45126032-50b69880-b13f-11e8-9c2c-abd16c433495.png\n :target: https://tidelift.com/subscription/pkg/pypi-apispec?utm_source=pypi-apispec&utm_medium=referral&utm_campaign=readme\n :alt: Get supported apispec with Tidelift\n\nSecurity Contact Information\n============================\n\nTo report a security vulnerability, please use the\n`Tidelift security contact <https://tidelift.com/security>`_.\nTidelift will coordinate the fix and disclosure.\n\nProject Links\n=============\n\n- Docs: https://apispec.readthedocs.io/\n- Changelog: https://apispec.readthedocs.io/en/latest/changelog.html\n- Contributing Guidelines: https://apispec.readthedocs.io/en/latest/contributing.html\n- PyPI: https://pypi.python.org/pypi/apispec\n- Issues: https://github.com/marshmallow-code/apispec/issues\n\n\nLicense\n=======\n\nMIT licensed. See the bundled `LICENSE <https://github.com/marshmallow-code/apispec/blob/dev/LICENSE>`_ file for more details.\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A pluggable API specification generator. Currently supports the OpenAPI Specification (f.k.a. the Swagger specification).",
"version": "6.8.0",
"project_urls": {
"Changelog": "https://apispec.readthedocs.io/en/latest/changelog.html",
"Funding": "https://opencollective.com/marshmallow",
"Issues": "https://github.com/marshmallow-code/apispec/issues",
"Source": "https://github.com/marshmallow-code/apispec",
"Tidelift": "https://tidelift.com/subscription/pkg/pypi-apispec?utm_source=pypi-apispec&utm_medium=pypi"
},
"split_keywords": [
"apispec",
" swagger",
" openapi",
" specification",
" oas",
" documentation",
" spec",
" rest",
" api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "48916c69bd0800cfb1906b43030903379f1f4b644430d8d76164687ba0f1ba5f",
"md5": "24306785bf6049a1f9ddfb5102c4d1e9",
"sha256": "09d0b43eaf95fb3e94b5b15ba6288e45ae8b9a922f73073345b606204589df34"
},
"downloads": -1,
"filename": "apispec-6.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "24306785bf6049a1f9ddfb5102c4d1e9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 30464,
"upload_time": "2024-12-02T23:00:22",
"upload_time_iso_8601": "2024-12-02T23:00:22.900700Z",
"url": "https://files.pythonhosted.org/packages/48/91/6c69bd0800cfb1906b43030903379f1f4b644430d8d76164687ba0f1ba5f/apispec-6.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "126681f6f31feafb0ee2f6c649ba33f4c768f837bbabef279f12053d00a7099d",
"md5": "89f6b8186a8772dcfc54aade5e3495e1",
"sha256": "861cca82bbc0652ca9acea896921b254944580342fde849f86f6dac1acc6ca96"
},
"downloads": -1,
"filename": "apispec-6.8.0.tar.gz",
"has_sig": false,
"md5_digest": "89f6b8186a8772dcfc54aade5e3495e1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 76919,
"upload_time": "2024-12-02T23:00:25",
"upload_time_iso_8601": "2024-12-02T23:00:25.154371Z",
"url": "https://files.pythonhosted.org/packages/12/66/81f6f31feafb0ee2f6c649ba33f4c768f837bbabef279f12053d00a7099d/apispec-6.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-02 23:00:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "marshmallow-code",
"github_project": "apispec",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "apispec"
}
JSON
