Welcome to spectree’s documentation!

GitHub Actions pypi versions Language grade: Python Documentation Status

Yet another library to generate OpenAPI document and validate request & response with Python annotations.

Features

  • Less boilerplate code, annotations are really easy-to-use
  • Generate API document with Redoc UI or Swagger UI
  • Validate query, JSON data, response data with pydantic
  • Current support:
    • Flask
    • Falcon
    • Starlette

Quick Start

install with pip: pip install spectree

Examples

Check the examples folder.

Step by Step

  1. Define your data structure used in (query, json, headers, cookies, resp) with pydantic.BaseModel
  2. create spectree.SpecTree instance with the web framework name you are using, like api = SpecTree('flask')
  3. api.validate decorate the route with
    • query
    • json
    • headers
    • cookies
    • resp
    • tags
  4. access these data with context(query, json, headers, cookies) (of course, you can access these from the original place where the framework offered)
    • flask: request.context
    • falcon: req.context
    • starlette: request.context
  5. register to the web application api.register(app)
  6. check the document at URL location /apidoc/redoc or /apidoc/swagger

FAQ

ValidationError: missing field for headers

The HTTP headers’ keys in Flask are capitalized, in Falcon are upper cases, in Starlette are lower cases.

Contents:

Indices and tables