Metadata-Version: 2.3
Name: apispec
Version: 6.8.1
Summary: A pluggable API specification generator. Currently supports the OpenAPI Specification (f.k.a. the Swagger specification).
Keywords: apispec,swagger,openapi,specification,oas,documentation,spec,rest,api
Author-email: Steven Loria <sloria1@gmail.com>
Maintainer-email: Steven Loria <sloria1@gmail.com>, Jérôme Lafréchoux <jerome@jolimont.fr>
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: packaging>=21.3
Requires-Dist: apispec[tests] ; extra == "dev"
Requires-Dist: tox ; extra == "dev"
Requires-Dist: pre-commit>=3.5,<5.0 ; extra == "dev"
Requires-Dist: apispec[marshmallow] ; extra == "docs"
Requires-Dist: pyyaml==6.0.2 ; extra == "docs"
Requires-Dist: sphinx==8.1.3 ; extra == "docs"
Requires-Dist: sphinx-issues==5.0.0 ; extra == "docs"
Requires-Dist: sphinx-rtd-theme==3.0.2 ; extra == "docs"
Requires-Dist: marshmallow>=3.18.0 ; extra == "marshmallow"
Requires-Dist: apispec[yaml, marshmallow] ; extra == "tests"
Requires-Dist: openapi-spec-validator==0.7.1 ; extra == "tests"
Requires-Dist: pytest ; extra == "tests"
Requires-Dist: PyYAML>=3.10 ; extra == "yaml"
Project-URL: Changelog, https://apispec.readthedocs.io/en/latest/changelog.html
Project-URL: Funding, https://opencollective.com/marshmallow
Project-URL: Issues, https://github.com/marshmallow-code/apispec/issues
Project-URL: Source, https://github.com/marshmallow-code/apispec
Project-URL: Tidelift, https://tidelift.com/subscription/pkg/pypi-apispec?utm_source=pypi-apispec&utm_medium=pypi
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: marshmallow
Provides-Extra: tests
Provides-Extra: yaml

*******
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 <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.