apispec


Nameapispec JSON
Version 6.6.0 PyPI version JSON
download
home_page
SummaryA pluggable API specification generator. Currently supports the OpenAPI Specification (f.k.a. the Swagger specification).
upload_time2024-03-15 08:17:41
maintainer
docs_urlNone
author
requires_python>=3.8
license
keywords apispec swagger openapi specification oas documentation spec rest api
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            *******
apispec
*******

.. image:: https://badgen.net/pypi/v/apispec
    :target: https://pypi.org/project/apispec/
    :alt: PyPI version

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

.. image:: https://readthedocs.org/projects/apispec/badge/
   :target: https://apispec.readthedocs.io/
   :alt: Documentation

.. image:: https://badgen.net/badge/marshmallow/3?list=1
    :target: https://marshmallow.readthedocs.io/en/latest/upgrading.html
    :alt: marshmallow 3 only

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

.. image:: https://badgen.net/badge/code%20style/black/000
    :target: https://github.com/ambv/black
    :alt: code style: black

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": "",
    "name": "apispec",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.8",
    "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": "",
    "author_email": "Steven Loria <sloria1@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/18/67/7c4a1c107c985d679e242500b9a3451742738ed9af9349d3a0219a35781a/apispec-6.6.0.tar.gz",
    "platform": null,
    "description": "*******\napispec\n*******\n\n.. image:: https://badgen.net/pypi/v/apispec\n    :target: https://pypi.org/project/apispec/\n    :alt: PyPI version\n\n.. 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.. image:: https://readthedocs.org/projects/apispec/badge/\n   :target: https://apispec.readthedocs.io/\n   :alt: Documentation\n\n.. 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.. 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.. image:: https://badgen.net/badge/code%20style/black/000\n    :target: https://github.com/ambv/black\n    :alt: code style: black\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": "",
    "summary": "A pluggable API specification generator. Currently supports the OpenAPI Specification (f.k.a. the Swagger specification).",
    "version": "6.6.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": "5034277b2cdfd0033648f92ac2153f4f36816211bb37322f74c9f384dd092dae",
                "md5": "d86dbc299e53e273ddb943d9c6f8e565",
                "sha256": "b5b22f5dba6cc69bd90e1075de20ae3d27b310a6250c66b0271aa50615eee72d"
            },
            "downloads": -1,
            "filename": "apispec-6.6.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "d86dbc299e53e273ddb943d9c6f8e565",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 30309,
            "upload_time": "2024-03-15T08:17:39",
            "upload_time_iso_8601": "2024-03-15T08:17:39.658716Z",
            "url": "https://files.pythonhosted.org/packages/50/34/277b2cdfd0033648f92ac2153f4f36816211bb37322f74c9f384dd092dae/apispec-6.6.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "18677c4a1c107c985d679e242500b9a3451742738ed9af9349d3a0219a35781a",
                "md5": "9d4ff38b869907685411f438989907d6",
                "sha256": "c0846f8eaa5119c46b2ecfe9bc24ed19dba8845f8655d00b51ddd296a10ea4cb"
            },
            "downloads": -1,
            "filename": "apispec-6.6.0.tar.gz",
            "has_sig": false,
            "md5_digest": "9d4ff38b869907685411f438989907d6",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 76220,
            "upload_time": "2024-03-15T08:17:41",
            "upload_time_iso_8601": "2024-03-15T08:17:41.912806Z",
            "url": "https://files.pythonhosted.org/packages/18/67/7c4a1c107c985d679e242500b9a3451742738ed9af9349d3a0219a35781a/apispec-6.6.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-03-15 08:17:41",
    "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"
}
        
Elapsed time: 0.39336s