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()
app.schema_generator = APISpecSchemaGenerator(
APISpec(
title="Example API",
version="1.0",
openapi_version="3.0.0",
info={"description": "explanation of the api purpose"},
plugins=[MarshmallowPlugin()],
)
)
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 apispec.ext.marshmallow import MarshmallowPlugin
from marshmallow import Schema, fields
from starlette.applications import Starlette
from starlette.endpoints import HTTPEndpoint
from starlette.schemas import OpenAPIResponse
from starlette_apispec import APISpecSchemaGenerator
class UserSchema(Schema):
username = fields.Str(required=True)
app = Starlette()
app.schema_generator = APISpecSchemaGenerator(
APISpec(
title="Example API",
version="1.0",
openapi_version="3.0.0",
info={"description": "explanation of the api purpose"},
plugins=[MarshmallowPlugin()],
)
)
app.schema_generator.spec.definition("User", schema=UserSchema)
@app.route("/users", methods=["GET", "HEAD"])
def list_users(request):
"""
responses:
200:
description: A list of users.
schema: UserSchema
examples:
[{"username": "tom"}, {"username": "lucy"}]
"""
raise NotImplementedError()
@app.route("/users", methods=["POST"])
def create_user(request):
"""
responses:
200:
description: A user.
schema: UserSchema
examples:
{"username": "tom"}
"""
raise NotImplementedError()
@app.route("/orgs")
class OrganisationsEndpoint(HTTPEndpoint):
def get(self, request):
"""
responses:
200:
description: A list of organisations.
examples:
[{"name": "Foo Corp."}, {"name": "Acme Ltd."}]
"""
raise NotImplementedError()
def post(self, request):
"""
responses:
200:
description: An organisation.
examples:
{"name": "Foo Corp."}
"""
raise NotImplementedError()
@app.route("/schema", methods=["GET"], include_in_schema=False)
def schema(request):
return OpenAPIResponse(app.schema)
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
Install dependencies
poetry install
Run tests
poetry run pytest -s --cov-report term-missing --cov=starlette_apispec tests/
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
Close
Hashes for starlette_apispec-1.0.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 181de975ff02f9c6f0da17743056edc7812a9033fff1cb41cbfc6bd041b2769e |
|
MD5 | a8d357c4e64c874e723f3b87f1cfe428 |
|
BLAKE2b-256 | 63f395ba98a9ddc97f53d5c9765cf301317935b1f714f5f9068e2cc37cfe0e57 |