API Documentation

flarchitect automatically generates an OpenAPI 3.0.2 document for every registered model. The specification powers an interactive documentation page which can be served with either Redoc or Swagger UI. The raw specification is standard OpenAPI and can be consumed by external tools such as Postman.

Documentation style

By default, flarchitect renders docs with Redoc. To switch to Swagger UI set API_DOCS_STYLE = “swagger” in your Flask configuration. The only accepted values are "redoc" and "swagger". Redoc provides a clean read-only reference, while Swagger UI adds an interactive “try it out” console:

app.config["API_DOCS_STYLE"] = "swagger"

The documentation itself is hosted at API_DOCUMENTATION_URL (default /docs).

Automatic generation

When API_CREATE_DOCS is enabled (it is True by default) the specification is built on start-up by inspecting the routes and schemas registered with flarchitect.Architect. Any models added later are included the next time the application boots.

Accessing the spec

The canonical JSON schema is served under the docs path at /docs/apispec.json and is configurable via API_DOCS_SPEC_ROUTE. The legacy top‑level path /openapi.json (API_SPEC_ROUTE) now redirects to the docs JSON and will be removed in a future release.

Security scheme

flarchitect defines a bearerAuth security scheme using HTTP bearer tokens with JWTs. Routes that require authentication reference this scheme via a security declaration instead of documenting an explicit Authorization header parameter.

Exporting to a file

To generate a static JSON document for deployment or tooling:

import json

with open("openapi.json", "w") as fh:
    json.dump(architect.api_spec.to_dict(), fh, indent=2)

Customising the document

A number of configuration keys let you tailor the output:

For example, to load a Markdown file into the specification’s info section:

app.config["API_DESCRIPTION"] = "docs/README.md"

The contents of docs/README.md are rendered in the spec’s info section.

See Configuration for the full list of options.

Grouping and aggregation cards

When API_ALLOW_GROUPBY or API_ALLOW_AGGREGATION is enabled the generated Redoc/Swagger spec automatically surfaces the extra query parameters. You will see dedicated cards explaining the groupby and aggregation syntax along with parameter entries for groupby and aggregation. This keeps the interactive docs aligned with the Grouping & Aggregation guide and helps client developers discover the available summarisation options.

Error responses in the spec

flarchitect includes common error responses in each operation based on your configuration and the route’s context:

  • 401/403: shown when API_AUTHENTICATE is enabled, or when a route explicitly declares them (e.g., /auth/refresh).

  • 429: shown when a rate limit is configured via API_RATE_LIMIT; standard rate-limit headers are documented.

  • 400: shown when a request body is validated (input schema present) or for list endpoints with filtering/pagination features enabled. When API_ALLOW_JOIN is enabled, invalid join tokens (unknown relationships) also produce 400 with a message like Invalid join model: <token>.

  • 422: shown on POST/PUT/PATCH for models, reflecting integrity/type errors.

  • 404: shown for single-resource lookups and relationship endpoints.

  • 409: shown for DELETE (conflicts with related data or cascade rules).

  • 500: included by default unless you override the error list.

You can override the default set for a specific route by supplying error_responses=[...] to @architect.schema_constructor.