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 hacktoberfest http-api json-schema marshmallow openapi openapi-specification openapi2 openapi3 pluggable python rest-api swagger

Last synced: 13 days ago
JSON representation

A pluggable API specification generator. Currently supports the OpenAPI Specification (f.k.a. the Swagger specification)..

Lists

README 

        
*******

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 `_ (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.