Skip to main content

Starlette's api document support

Project description

# Starchart

## API document support for Starlette project

![Code Coverage](

## Features

* Inherit `starlette.schemas.BaseSchemaGenerator`
* Support OpenAPI 2 and 3, define API schema by your way
* Provide configurable [SwaggerUI](
* ...

## Install

pip install -U starchart

## Tutorial

Let see a simple example app:
"""OpenAPI2(Swagger) example
from functools import partial

from starlette.applications import Starlette
from starlette.requests import Request
from starlette.responses import JSONResponse
from starlette.endpoints import HTTPEndpoint
from uvicorn import run

from starchart.generators import SchemaGenerator
from starchart.endpoints import UI, Schema

app = Starlette(debug=True)

app.schema_generator = SchemaGenerator(
title="Cat store",
description="Cat store api document",
# define data
CATS = {
1: {"id": 1, "name": "DangDang", "age": 2},
2: {"id": 2, "name": "DingDing", "age": 1},
# add schema
"properties": {
"id": {"description": "global unique", "type": "integer"},
"name": {"type": "string"},
"age": {"type": "integer"},
"type": "object",

# define routes and schema(in doc string)
class Cat(HTTPEndpoint):
def get(self, req: Request):
summary: Get single cat
- cat
- name: id
type: integer
in: query
required: True
description: OK
$ref: '#/definitions/Cat'
description: Not found
return JSONResponse(CATS[1])

def delete(self, req: Request):
summary: Delete single cat
- cat
- name: id
type: integer
in: query
required: True
description: OK
$ref: '#/definitions/Cat'
description: Not found
cat = CATS.pop(1)
return JSONResponse(cat)

# define doc by yaml or json file
@app.route("/cats/", methods=["GET"])
def list_cats(req: Request):
return JSONResponse(list(CATS.values()))

@app.route("/cats/", methods=["POST"])
async def list_cats(req: Request):
cat = await req.json()
CATS[cat["id"]] = cat
return JSONResponse(cat)

# add document's endpoints
schema_path = "/docs/schema/"
app.add_route("/docs/", UI, methods=["GET"], name="SwaggerUI", include_in_schema=False)
schema_path, Schema, methods=["GET"], name="SwaggerSchema", include_in_schema=False
# config endpoints
UI.CONTEXT["schema_url"] = schema_path
Schema.SCHEMA_LOADER = partial(app.schema_generator.get_schema, app.routes)


Then we can get swagger UI:

## More examples

See **examples/**

## Details

### How can I define endpoints schema?

* Function or method's docstring
* From yaml or json file(by `schema_from`)
* ...

### How the swagger UI works?

We provide two endpoints: a standard web page (see *starchart/static/index.html*) and a
standard schema api


- [x] OpenAPI3 example app
- [ ] Redoc UI support
- [ ] Provide a Starlette extension, make it easier to integrate your projects
- [ ] Requset/Response validation by defined schema

Project details

Download files

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

Files for starchart, version 0.1.0
Filename, size File type Python version Upload date Hashes
Filename, size starchart-0.1.0.tar.gz (55.1 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page