Skip to main content

Starlette's api document support

Project description

# Starchart

## API document support for Starlette project

![Build](https://travis-ci.com/strongbugman/starchart.svg?branch=master)
![Code Coverage](https://codecov.io/gh/strongbugman/starchart/branch/master/graph/badge.svg)

## Features

* Inherit `starlette.schemas.BaseSchemaGenerator`
* Support OpenAPI 2 and 3, define API schema by your way
* Provide configurable [SwaggerUI](http://swagger.io/swagger-ui/)
* ...

## Install

```shell
pip install -U starchart
```

## Tutorial

Let see a simple example app:
```python
"""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 SwaggerUI, RedocUI, Schema


app = Starlette(debug=True)

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


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

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


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


@app.route("/cats/", methods=["POST"])
@app.schema_generator.schema_from("./examples/docs/cats_post.json")
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/swagger/",
SwaggerUI,
methods=["GET"],
name="SwaggerUI",
include_in_schema=False,
)
app.add_route(
"/docs/redoc/", RedocUI, methods=["GET"], name="SwaggerUI", include_in_schema=False
)
app.add_route(
schema_path, Schema, methods=["GET"], name="SwaggerSchema", include_in_schema=False
)
# config endpoints
SwaggerUI.set_schema_url(schema_path)
RedocUI.set_schema_url(schema_path)
Schema.set_schema_loader(partial(app.schema_generator.get_schema, app.routes))

run(app)
```

Then we can get swagger UI:
![](docs/SwaggerUI.jpg)

## 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


## TODO

- [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.

Source Distribution

starchart-0.2.0.tar.gz (55.6 kB view details)

Uploaded Source

File details

Details for the file starchart-0.2.0.tar.gz.

File metadata

  • Download URL: starchart-0.2.0.tar.gz
  • Upload date:
  • Size: 55.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: Python-urllib/3.6

File hashes

Hashes for starchart-0.2.0.tar.gz
Algorithm Hash digest
SHA256 6c3516bb8d909c2078de9d4ce7ef956e78f2dd3928817c364fb0b6f0b53707f9
MD5 d77fc851f5ad773eca85d1af5225a33d
BLAKE2b-256 2e65c779cdf91cb1f78566baa01c4b49b2233484d95ec754ed0eb6c358623756

See more details on using hashes here.

Supported by

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