APISpec support for starlette
Project description
Easy APISpec integration for Starlette
from apispec import APISpec
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=["apispec.ext.marshmallow"],
)
)
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: 0.39.0
Usage
This example includes marshmallow integration
from apispec import APISpec
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=["apispec.ext.marshmallow"],
)
)
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-0.1.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6eaf67cd521c6ff2c7f9e752df189250c43f662a53e4459159001873b46130a7 |
|
MD5 | b5ce0d42adaa7ff7c4b5ac2616e37a2d |
|
BLAKE2b-256 | c1a044721f602d323784c19234f92138316cec7b293e4ffd6a81ca0e94b64653 |