Skip to main content

APISpec support for starlette

Project description

Easy APISpec integration for Starlette

GitHub Workflow Status Codecov PyPI PyPI - Python Version
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:

Starlette documentation

APISpec documentation

Testing

  1. Clone the repo

  2. Activate venv . venv/bin/activate

  3. Install dependencies

poetry install
  1. Run tests

./scripts/test

Contributing

PRs are welcome!

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

starlette_apispec-2.2.1.tar.gz (4.1 kB view details)

Uploaded Source

Built Distribution

starlette_apispec-2.2.1-py3-none-any.whl (4.4 kB view details)

Uploaded Python 3

File details

Details for the file starlette_apispec-2.2.1.tar.gz.

File metadata

  • Download URL: starlette_apispec-2.2.1.tar.gz
  • Upload date:
  • Size: 4.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.7.1 CPython/3.12.1 Linux/6.2.0-1019-azure

File hashes

Hashes for starlette_apispec-2.2.1.tar.gz
Algorithm Hash digest
SHA256 b2cd3721a3cc7ebc31610e8470c12c6efff453a5732892285e4076c73f164f96
MD5 f0388b7b287fb2bc161e7527a4757193
BLAKE2b-256 06f3f8678f7fc5e432c52ea6dac6072c6083d56c69e8f1e0e170c908681284bc

See more details on using hashes here.

File details

Details for the file starlette_apispec-2.2.1-py3-none-any.whl.

File metadata

  • Download URL: starlette_apispec-2.2.1-py3-none-any.whl
  • Upload date:
  • Size: 4.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.7.1 CPython/3.12.1 Linux/6.2.0-1019-azure

File hashes

Hashes for starlette_apispec-2.2.1-py3-none-any.whl
Algorithm Hash digest
SHA256 14b64f8551a06f2d4f1762940a0b4e1ec6c87b85d945bbc8dc8bfcf30e592ce6
MD5 2c2ccfd146732de3e8a6ce02c57ec57d
BLAKE2b-256 34004155910178cd10828746e005e957ffae6d1f04e943b0ff6155912110e17b

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page