API Documentation

API Star can build API documentation from an OpenAPI or Swagger schema. It supports a number of different themes, and the command line tool allows you to preview the documentation as you edit the schema.

$ apistar docs --path schema.json --format openapi`
✓ Documentation built at "build/index.html".


Configure the defaults for apistar docs using an apistar.yml file.

    path: schema.json
    format: openapi
    output_dir: docs
    theme: apistar

Now you can build the documentation like so:

$ apistar docs
✓ Documentation built at "docs/index.html".

The documentation is a static HTML build and can be hosted anywhere.

Previewing the API documentation

To preview the API documentation use apistar docs --serve, which will build the documentation, and then start up a webserver.

$ apistar docs --serve
✓ Documentation available at "" (Ctrl+C to quit)

Programmatic interface

You can also build API documentation using a programmatic interface. This allows you to dynamically serve API documentation from any Python web server that is able to generate an OpenAPI or Swagger specification.

import apistar

schema = """
openapi: 3.0.0
  title: Widget API
  version: '1.0'
  description: An example API for widgets
      summary: List all the widgets.
      operationId: listWidgets
      - in: query
        name: search
        description: Filter widgets by this search term.
          type: string

index_html = apistar.docs(schema, schema_url='/schema.yaml', static_url='/static/')

If you're serving the documentation dynamically, then you'll also need to make sure that your framework serves up the API schema, and the static media for the documentation theme.

Function signature: docs(schema, format=None, encoding=None, theme="apistar", schema_url=None, static_url=None)