==================
Starlette APISpec
==================
Easy APISpec integration for Starlette
.. image:: https://github.com/Woile/starlette-apispec/actions/workflows/pythonpackage.yml/badge.svg?style=flat-square
:alt: GitHub Workflow Status
:target: https://github.com/Woile/starlette-apispec/actions/workflows/pythonpackage.yml
.. image:: https://img.shields.io/codecov/c/github/Woile/starlette-apispec.svg?style=flat-square
:alt: Codecov
:target: https://codecov.io/gh/Woile/starlette-apispec
.. image:: https://img.shields.io/pypi/v/starlette-apispec.svg?style=flat-square
:alt: PyPI
:target: https://pypi.org/project/starlette-apispec/
.. image:: https://img.shields.io/pypi/pyversions/starlette-apispec.svg?style=flat-square
:alt: PyPI - Python Version
:target: https://pypi.org/project/starlette-apispec/
.. contents::
:depth: 2
.. code-block:: python
from apispec import APISpec
from apispec.ext.marshmallow import MarshmallowPlugin
from starlette.applications import Starlette
from starlette_apispec import APISpecSchemaGenerator
app = Starlette()
schemas = APISpecSchemaGenerator(
APISpec(
title="Example API",
version="1.0",
openapi_version="3.0.0",
info={"description": "explanation of the api purpose"},
plugins=[MarshmallowPlugin()],
)
)
@app.route("/schema", methods=["GET"], include_in_schema=False)
def schema(request):
return schemas.OpenAPIResponse(request=request)
Installation
============
::
pip install -U starlette-apispec
Alternatively you can do
::
poetry add starlette-apispec
About
-----
This library helps you easily document your REST API built with starlette.
Starlette_ is a is a lightweight ASGI framework/toolkit,
which is ideal for building high performance asyncio services.
APISpec_ supports the `OpenApi Specification <https://github.com/OAI/OpenAPI-Specification>`_
and it has some useful plugins like marshmallow_ support.
Version supported: :code:`^1.0.0`
Usage
=====
This example includes marshmallow_ integration
.. code-block:: python
from apispec import APISpec
from starlette.applications import Starlette
from starlette.endpoints import HTTPEndpoint
from starlette.testclient import TestClient
from starlette_apispec import APISpecSchemaGenerator
app = Starlette()
schemas = APISpecSchemaGenerator(
APISpec(
title="Example API",
version="1.0",
openapi_version="3.0.0",
info={"description": "explanation of the api purpose"},
)
)
@app.websocket_route("/ws")
def ws(session):
"""ws"""
pass # pragma: no cover
@app.route("/users", methods=["GET", "HEAD"])
def list_users(request):
"""
responses:
200:
description: A list of users.
examples:
[{"username": "tom"}, {"username": "lucy"}]
"""
pass # pragma: no cover
@app.route("/users", methods=["POST"])
def create_user(request):
"""
responses:
200:
description: A user.
examples:
{"username": "tom"}
"""
pass # pragma: no cover
@app.route("/orgs")
class OrganisationsEndpoint(HTTPEndpoint):
def get(self, request):
"""
responses:
200:
description: A list of organisations.
examples:
[{"name": "Foo Corp."}, {"name": "Acme Ltd."}]
"""
pass # pragma: no cover
def post(self, request):
"""
responses:
200:
description: An organisation.
examples:
{"name": "Foo Corp."}
"""
pass # pragma: no cover
@app.route("/schema", methods=["GET"], include_in_schema=False)
def schema(request):
return schemas.OpenAPIResponse(request=request)
More documentation
==================
This package is basically a proxy, so if you wonder how to do something,
here are the sources you need:
`Starlette documentation`_
`APISpec documentation`_
Testing
=======
1. Clone the repo
2. Activate venv ``. venv/bin/activate``
3. Install dependencies
::
poetry install
4. Run tests
::
./scripts/test
Contributing
============
**PRs are welcome!**
.. _marshmallow: https://marshmallow.readthedocs.io/
.. _APISpec: https://apispec.readthedocs.io/en/stable/
.. _Starlette: https://www.starlette.io/
.. _`Starlette documentation`: https://www.starlette.io/
.. _`APISpec documentation`: https://apispec.readthedocs.io/en/stable/
Raw data
{
"_id": null,
"home_page": "https://github.com/Woile/starlette-apispec",
"name": "starlette-apispec",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "openapi,api,swagger",
"author": "Santiago Fraire Willemoes",
"author_email": "santiwilly@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/06/f3/f8678f7fc5e432c52ea6dac6072c6083d56c69e8f1e0e170c908681284bc/starlette_apispec-2.2.1.tar.gz",
"platform": null,
"description": "==================\nStarlette APISpec\n==================\n\n Easy APISpec integration for Starlette\n\n\n.. image:: https://github.com/Woile/starlette-apispec/actions/workflows/pythonpackage.yml/badge.svg?style=flat-square\n :alt: GitHub Workflow Status\n :target: https://github.com/Woile/starlette-apispec/actions/workflows/pythonpackage.yml\n\n.. image:: https://img.shields.io/codecov/c/github/Woile/starlette-apispec.svg?style=flat-square\n :alt: Codecov\n :target: https://codecov.io/gh/Woile/starlette-apispec\n\n.. image:: https://img.shields.io/pypi/v/starlette-apispec.svg?style=flat-square\n :alt: PyPI\n :target: https://pypi.org/project/starlette-apispec/\n\n.. image:: https://img.shields.io/pypi/pyversions/starlette-apispec.svg?style=flat-square\n :alt: PyPI - Python Version\n :target: https://pypi.org/project/starlette-apispec/\n\n.. contents::\n :depth: 2\n\n.. code-block:: python\n\n from apispec import APISpec\n from apispec.ext.marshmallow import MarshmallowPlugin\n from starlette.applications import Starlette\n from starlette_apispec import APISpecSchemaGenerator\n\n app = Starlette()\n\n schemas = APISpecSchemaGenerator(\n APISpec(\n title=\"Example API\",\n version=\"1.0\",\n openapi_version=\"3.0.0\",\n info={\"description\": \"explanation of the api purpose\"},\n plugins=[MarshmallowPlugin()],\n )\n )\n\n @app.route(\"/schema\", methods=[\"GET\"], include_in_schema=False)\n def schema(request):\n return schemas.OpenAPIResponse(request=request)\n\n\nInstallation\n============\n\n::\n\n pip install -U starlette-apispec\n\nAlternatively you can do\n\n::\n\n poetry add starlette-apispec\n\nAbout\n-----\n\nThis library helps you easily document your REST API built with starlette.\n\nStarlette_ is a is a lightweight ASGI framework/toolkit,\nwhich is ideal for building high performance asyncio services.\n\nAPISpec_ supports the `OpenApi Specification <https://github.com/OAI/OpenAPI-Specification>`_\nand it has some useful plugins like marshmallow_ support.\n\nVersion supported: :code:`^1.0.0`\n\n\nUsage\n=====\n\n\nThis example includes marshmallow_ integration\n\n.. code-block:: python\n\n from apispec import APISpec\n\n from starlette.applications import Starlette\n from starlette.endpoints import HTTPEndpoint\n from starlette.testclient import TestClient\n\n from starlette_apispec import APISpecSchemaGenerator\n\n\n app = Starlette()\n\n schemas = APISpecSchemaGenerator(\n APISpec(\n title=\"Example API\",\n version=\"1.0\",\n openapi_version=\"3.0.0\",\n info={\"description\": \"explanation of the api purpose\"},\n )\n )\n\n\n @app.websocket_route(\"/ws\")\n def ws(session):\n \"\"\"ws\"\"\"\n pass # pragma: no cover\n\n\n @app.route(\"/users\", methods=[\"GET\", \"HEAD\"])\n def list_users(request):\n \"\"\"\n responses:\n 200:\n description: A list of users.\n examples:\n [{\"username\": \"tom\"}, {\"username\": \"lucy\"}]\n \"\"\"\n pass # pragma: no cover\n\n\n @app.route(\"/users\", methods=[\"POST\"])\n def create_user(request):\n \"\"\"\n responses:\n 200:\n description: A user.\n examples:\n {\"username\": \"tom\"}\n \"\"\"\n pass # pragma: no cover\n\n\n @app.route(\"/orgs\")\n class OrganisationsEndpoint(HTTPEndpoint):\n def get(self, request):\n \"\"\"\n responses:\n 200:\n description: A list of organisations.\n examples:\n [{\"name\": \"Foo Corp.\"}, {\"name\": \"Acme Ltd.\"}]\n \"\"\"\n pass # pragma: no cover\n\n def post(self, request):\n \"\"\"\n responses:\n 200:\n description: An organisation.\n examples:\n {\"name\": \"Foo Corp.\"}\n \"\"\"\n pass # pragma: no cover\n\n\n @app.route(\"/schema\", methods=[\"GET\"], include_in_schema=False)\n def schema(request):\n return schemas.OpenAPIResponse(request=request)\n\nMore documentation\n==================\n\nThis package is basically a proxy, so if you wonder how to do something,\nhere are the sources you need:\n\n`Starlette documentation`_\n\n`APISpec documentation`_\n\n\nTesting\n=======\n\n1. Clone the repo\n2. Activate venv ``. venv/bin/activate``\n3. Install dependencies\n\n::\n\n poetry install\n\n4. Run tests\n\n::\n\n ./scripts/test\n\n\nContributing\n============\n\n**PRs are welcome!**\n\n\n.. _marshmallow: https://marshmallow.readthedocs.io/\n.. _APISpec: https://apispec.readthedocs.io/en/stable/\n.. _Starlette: https://www.starlette.io/\n.. _`Starlette documentation`: https://www.starlette.io/\n.. _`APISpec documentation`: https://apispec.readthedocs.io/en/stable/\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "APISpec support for starlette",
"version": "2.2.1",
"project_urls": {
"Homepage": "https://github.com/Woile/starlette-apispec"
},
"split_keywords": [
"openapi",
"api",
"swagger"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "34004155910178cd10828746e005e957ffae6d1f04e943b0ff6155912110e17b",
"md5": "2c2ccfd146732de3e8a6ce02c57ec57d",
"sha256": "14b64f8551a06f2d4f1762940a0b4e1ec6c87b85d945bbc8dc8bfcf30e592ce6"
},
"downloads": -1,
"filename": "starlette_apispec-2.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2c2ccfd146732de3e8a6ce02c57ec57d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 4396,
"upload_time": "2024-02-06T08:22:05",
"upload_time_iso_8601": "2024-02-06T08:22:05.752855Z",
"url": "https://files.pythonhosted.org/packages/34/00/4155910178cd10828746e005e957ffae6d1f04e943b0ff6155912110e17b/starlette_apispec-2.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "06f3f8678f7fc5e432c52ea6dac6072c6083d56c69e8f1e0e170c908681284bc",
"md5": "f0388b7b287fb2bc161e7527a4757193",
"sha256": "b2cd3721a3cc7ebc31610e8470c12c6efff453a5732892285e4076c73f164f96"
},
"downloads": -1,
"filename": "starlette_apispec-2.2.1.tar.gz",
"has_sig": false,
"md5_digest": "f0388b7b287fb2bc161e7527a4757193",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 4051,
"upload_time": "2024-02-06T08:22:07",
"upload_time_iso_8601": "2024-02-06T08:22:07.450660Z",
"url": "https://files.pythonhosted.org/packages/06/f3/f8678f7fc5e432c52ea6dac6072c6083d56c69e8f1e0e170c908681284bc/starlette_apispec-2.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-06 08:22:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Woile",
"github_project": "starlette-apispec",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "starlette-apispec"
}
JSON
