APISpec support for starlette
Project description
Easy APISpec integration for Starlette
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 and it has some useful plugins like marshmallow support.
Version supported: ^1.0.0
Usage
This example includes marshmallow integration
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:
Testing
Clone the repo
Activate venv . venv/bin/activate
Install dependencies
poetry install
Run tests
./scripts/test
Contributing
PRs are welcome!
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for starlette_apispec-2.2.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 14b64f8551a06f2d4f1762940a0b4e1ec6c87b85d945bbc8dc8bfcf30e592ce6 |
|
MD5 | 2c2ccfd146732de3e8a6ce02c57ec57d |
|
BLAKE2b-256 | 34004155910178cd10828746e005e957ffae6d1f04e943b0ff6155912110e17b |