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.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 19ede7f7179a7d25537bb1065aaad9cc85888a0ae24a3ff38118b07fe9f46eb2 |
|
MD5 | 0d56554cae67bf52aa5ac12c7e04643f |
|
BLAKE2b-256 | 48509564020e1da4b64aa3d3189ce4acd86ed313374de4ca9df69c228d70c091 |