***************
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"
}
JSON
