apispec-plugins


Nameapispec-plugins JSON
Version 1.1.0 PyPI version JSON
download
home_pagehttps://github.com/codectl/apispec-plugins
SummaryPlugins for apispec
upload_time2023-03-26 14:12:14
maintainer
docs_urlNone
authorRenato Damas
requires_python>=3.8,<4.0
licenseMIT
keywords apispec plugins swagger openapi oas2 oas3 specification documentation spec rest api web flask pydantic python python3
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            ***************
apispec-plugins
***************

.. image:: https://img.shields.io/pypi/v/apispec-plugins
    :target: https://pypi.org/project/apispec-plugins
    :alt: PyPI version
.. image:: https://github.com/codectl/apispec-plugins/actions/workflows/ci.yaml/badge.svg
    :target: https://github.com/codectl/apispec-plugins/actions/workflows/ci.yaml
    :alt: CI
.. image:: https://codecov.io/gh/codectl/apispec-plugins/branch/master/graph/badge.svg
    :target: https://app.codecov.io/gh/codectl/apispec-plugins/branch/master
    :alt: codecov
.. image:: https://img.shields.io/badge/OAS-2_|_3-14ACBB.svg
    :target: https://github.com/OAI/OpenAPI-Specification
    :alt: OpenAPI Specification 2/3 compatible
.. image:: https://img.shields.io/pypi/pyversions/apispec-plugins
    :target: https://pypi.org/project/apispec-plugins
    :alt: Python compatibility
.. image:: https://img.shields.io/badge/code_style-black-000000.svg
    :target: https://github.com/psf/black
    :alt: code style: black
.. image:: https://img.shields.io/badge/License-MIT-yellow.svg
    :target: https://opensource.org/licenses/MIT
    :alt: license: MIT

`APISpec <https://github.com/marshmallow-code/apispec>`__ plugins for easy
integration with different components (web frameworks, packages, etc).

Features
========
* Support for the OpenAPI Specification (versions 2 and 3)
* Support for frameworks/plugins which include:

  * ``apispec_plugins.webframeworks.flask``
  * ``apispec_plugins.ext.pydantic``

Installation
============
Install the package directly from ``PyPI`` (recommended):

.. code-block:: bash

   $ pip install apispec-plugins

Plugin dependencies like ``flask`` and ``pydantic`` are not installed with the package by default. To
have ``flask`` and ``pydantic`` installed, run:

.. code-block:: bash

   $ pip install apispec-plugins[flask,pydantic]

Example Usage
=============
.. code-block:: python

    from typing import Optional

    from apispec import APISpec
    from apispec_plugins.base.mixin import RegistryMixin
    from apispec_plugins.ext.pydantic import PydanticPlugin
    from apispec_plugins.webframeworks.flask import FlaskPlugin
    from flask import Flask
    from pydantic import BaseModel


    # set APISpec plugins
    spec = APISpec(
        title="Pet Store",
        version="1.0.0",
        openapi_version="3.0.3",
        info=dict(description="A minimal pet store API"),
        plugins=(FlaskPlugin(), PydanticPlugin()),
    )


    # optional Flask support
    app = Flask(__name__)


    # optional pydantic support
    class Pet(BaseModel, RegistryMixin):
        id: Optional[int]
        name: str


    @app.route("/pet/<petId>")
    def pet(petId):
        """Find pet by ID.
        ---
        get:
            parameters:
                - in: path
                  name: petId
            responses:
                 200:
                     description: display pet data
                     content:
                         application/json:
                             schema: Pet
        """
        return f"Display pet with ID {petId}"

        # register `path` for the Flask route
        with app.test_request_context():
            spec.path(view=pet)

Alternatively, to ``Flask`` routes, ``MethodView`` can be used:

.. code-block:: python

   from flask.views import MethodView


   class PetAPI(MethodView):
       def get(self, petId):
           # get pet by ID
           pass


   app.add_url_rule("/pet/<petId>", view_func=PetAPI.as_view("pet_view"))

Dynamic specs
-------------
As seen so far, specs are specified in the docstring of the view or
class. However, with the ``spec_from`` decorator, one can dynamically
set specs:

.. code-block:: python

   from apispec_plugins import spec_from


   @spec_from(
       {
           "parameters": {"in": "path", "name": "petId"},
           "responses": {200: {"description": "display pet data"}},
       }
   )
   def pet(petID):
       """Find pet by ID."""
       pass

Why not ``apispec-webframeworks``?
==================================
The conceiving of this project was based on `apispec-webframeworks <https://github.com/marshmallow-code/
apispec-webframeworks>`__. While that project is focused on integrating web frameworks with ``APISpec``, this
project goes a step further in providing the best integration possible with the ``APISpec`` standards. Some
limitations on that project were also addressed, like:

* a path cannot register no more than 1 single rule per endpoint;
* limited docstring spec processing;

Tests & linting 🚥
==================
Run tests with ``tox``:

.. code-block:: bash

    # ensure tox is installed
    $ tox

Run linter only:

.. code-block:: bash

    $ tox -e lint

Optionally, run coverage as well with:

.. code-block:: bash

    $ tox -e coverage

License
=======
MIT licensed. See `LICENSE <LICENSE>`__.

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/codectl/apispec-plugins",
    "name": "apispec-plugins",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.8,<4.0",
    "maintainer_email": "",
    "keywords": "apispec,plugins,swagger,openapi,oas2,oas3,specification,documentation,spec,rest,api,web,flask,pydantic,python,python3",
    "author": "Renato Damas",
    "author_email": "rena2damas@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/91/c3/d68104e27ccecb8bbab2cbcddb2764d7faf6fd4b3cee65b985e8c8fed558/apispec_plugins-1.1.0.tar.gz",
    "platform": null,
    "description": "***************\napispec-plugins\n***************\n\n.. image:: https://img.shields.io/pypi/v/apispec-plugins\n    :target: https://pypi.org/project/apispec-plugins\n    :alt: PyPI version\n.. image:: https://github.com/codectl/apispec-plugins/actions/workflows/ci.yaml/badge.svg\n    :target: https://github.com/codectl/apispec-plugins/actions/workflows/ci.yaml\n    :alt: CI\n.. image:: https://codecov.io/gh/codectl/apispec-plugins/branch/master/graph/badge.svg\n    :target: https://app.codecov.io/gh/codectl/apispec-plugins/branch/master\n    :alt: codecov\n.. image:: https://img.shields.io/badge/OAS-2_|_3-14ACBB.svg\n    :target: https://github.com/OAI/OpenAPI-Specification\n    :alt: OpenAPI Specification 2/3 compatible\n.. image:: https://img.shields.io/pypi/pyversions/apispec-plugins\n    :target: https://pypi.org/project/apispec-plugins\n    :alt: Python compatibility\n.. image:: https://img.shields.io/badge/code_style-black-000000.svg\n    :target: https://github.com/psf/black\n    :alt: code style: black\n.. image:: https://img.shields.io/badge/License-MIT-yellow.svg\n    :target: https://opensource.org/licenses/MIT\n    :alt: license: MIT\n\n`APISpec <https://github.com/marshmallow-code/apispec>`__ plugins for easy\nintegration with different components (web frameworks, packages, etc).\n\nFeatures\n========\n* Support for the OpenAPI Specification (versions 2 and 3)\n* Support for frameworks/plugins which include:\n\n  * ``apispec_plugins.webframeworks.flask``\n  * ``apispec_plugins.ext.pydantic``\n\nInstallation\n============\nInstall the package directly from ``PyPI`` (recommended):\n\n.. code-block:: bash\n\n   $ pip install apispec-plugins\n\nPlugin dependencies like ``flask`` and ``pydantic`` are not installed with the package by default. To\nhave ``flask`` and ``pydantic`` installed, run:\n\n.. code-block:: bash\n\n   $ pip install apispec-plugins[flask,pydantic]\n\nExample Usage\n=============\n.. code-block:: python\n\n    from typing import Optional\n\n    from apispec import APISpec\n    from apispec_plugins.base.mixin import RegistryMixin\n    from apispec_plugins.ext.pydantic import PydanticPlugin\n    from apispec_plugins.webframeworks.flask import FlaskPlugin\n    from flask import Flask\n    from pydantic import BaseModel\n\n\n    # set APISpec plugins\n    spec = APISpec(\n        title=\"Pet Store\",\n        version=\"1.0.0\",\n        openapi_version=\"3.0.3\",\n        info=dict(description=\"A minimal pet store API\"),\n        plugins=(FlaskPlugin(), PydanticPlugin()),\n    )\n\n\n    # optional Flask support\n    app = Flask(__name__)\n\n\n    # optional pydantic support\n    class Pet(BaseModel, RegistryMixin):\n        id: Optional[int]\n        name: str\n\n\n    @app.route(\"/pet/<petId>\")\n    def pet(petId):\n        \"\"\"Find pet by ID.\n        ---\n        get:\n            parameters:\n                - in: path\n                  name: petId\n            responses:\n                 200:\n                     description: display pet data\n                     content:\n                         application/json:\n                             schema: Pet\n        \"\"\"\n        return f\"Display pet with ID {petId}\"\n\n        # register `path` for the Flask route\n        with app.test_request_context():\n            spec.path(view=pet)\n\nAlternatively, to ``Flask`` routes, ``MethodView`` can be used:\n\n.. code-block:: python\n\n   from flask.views import MethodView\n\n\n   class PetAPI(MethodView):\n       def get(self, petId):\n           # get pet by ID\n           pass\n\n\n   app.add_url_rule(\"/pet/<petId>\", view_func=PetAPI.as_view(\"pet_view\"))\n\nDynamic specs\n-------------\nAs seen so far, specs are specified in the docstring of the view or\nclass. However, with the ``spec_from`` decorator, one can dynamically\nset specs:\n\n.. code-block:: python\n\n   from apispec_plugins import spec_from\n\n\n   @spec_from(\n       {\n           \"parameters\": {\"in\": \"path\", \"name\": \"petId\"},\n           \"responses\": {200: {\"description\": \"display pet data\"}},\n       }\n   )\n   def pet(petID):\n       \"\"\"Find pet by ID.\"\"\"\n       pass\n\nWhy not ``apispec-webframeworks``?\n==================================\nThe conceiving of this project was based on `apispec-webframeworks <https://github.com/marshmallow-code/\napispec-webframeworks>`__. While that project is focused on integrating web frameworks with ``APISpec``, this\nproject goes a step further in providing the best integration possible with the ``APISpec`` standards. Some\nlimitations on that project were also addressed, like:\n\n* a path cannot register no more than 1 single rule per endpoint;\n* limited docstring spec processing;\n\nTests & linting \ud83d\udea5\n==================\nRun tests with ``tox``:\n\n.. code-block:: bash\n\n    # ensure tox is installed\n    $ tox\n\nRun linter only:\n\n.. code-block:: bash\n\n    $ tox -e lint\n\nOptionally, run coverage as well with:\n\n.. code-block:: bash\n\n    $ tox -e coverage\n\nLicense\n=======\nMIT licensed. See `LICENSE <LICENSE>`__.\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Plugins for apispec",
    "version": "1.1.0",
    "split_keywords": [
        "apispec",
        "plugins",
        "swagger",
        "openapi",
        "oas2",
        "oas3",
        "specification",
        "documentation",
        "spec",
        "rest",
        "api",
        "web",
        "flask",
        "pydantic",
        "python",
        "python3"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "f362271f65382d262359a011e1e2f4e2956ada3c37fa37a63b1eb732d6358d6d",
                "md5": "1397addb18c38faccef5a36b96593e7f",
                "sha256": "759458fd3358fbdd10920dfaa2494bac3882d8d6dd4f97c0977923ca19922c38"
            },
            "downloads": -1,
            "filename": "apispec_plugins-1.1.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "1397addb18c38faccef5a36b96593e7f",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8,<4.0",
            "size": 10655,
            "upload_time": "2023-03-26T14:12:12",
            "upload_time_iso_8601": "2023-03-26T14:12:12.688142Z",
            "url": "https://files.pythonhosted.org/packages/f3/62/271f65382d262359a011e1e2f4e2956ada3c37fa37a63b1eb732d6358d6d/apispec_plugins-1.1.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "91c3d68104e27ccecb8bbab2cbcddb2764d7faf6fd4b3cee65b985e8c8fed558",
                "md5": "fafe0a267aba69cdf4057cd5393279c0",
                "sha256": "3c157c127fc1cd7bafa98324f1c76fefc466cd452aa10cd0f77555f36bbe8dd2"
            },
            "downloads": -1,
            "filename": "apispec_plugins-1.1.0.tar.gz",
            "has_sig": false,
            "md5_digest": "fafe0a267aba69cdf4057cd5393279c0",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8,<4.0",
            "size": 9816,
            "upload_time": "2023-03-26T14:12:14",
            "upload_time_iso_8601": "2023-03-26T14:12:14.481120Z",
            "url": "https://files.pythonhosted.org/packages/91/c3/d68104e27ccecb8bbab2cbcddb2764d7faf6fd4b3cee65b985e8c8fed558/apispec_plugins-1.1.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-03-26 14:12:14",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "github_user": "codectl",
    "github_project": "apispec-plugins",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "tox": true,
    "lcname": "apispec-plugins"
}
        
Elapsed time: 0.04985s