OpenAPI

Piccolo API has great support for viewing OpenAPI schemas using SwaggerUI.

Source

piccolo_api.openapi.endpoints.swagger_ui(schema_url: str = '/openapi.json', swagger_ui_title: str = 'Piccolo Swagger UI', csrf_cookie_name: str | None = DEFAULT_COOKIE_NAME, csrf_header_name: str | None = DEFAULT_HEADER_NAME, swagger_ui_version: str = '5')[source]

Even though ASGI frameworks such as FastAPI and BlackSheep have endpoints for viewing OpenAPI / Swagger docs, out of the box they don’t work well with some Piccolo middleware (namely CSRF middleware, which requires Swagger UI to add the CSRF token to the header of each API call).

By using this endpoint instead, it will work correctly with CSRF.

FastAPI example

from fastapi import FastAPI
from piccolo_api.openapi.endpoints import swagger_ui

# By setting these values to None, we disable the builtin endpoints.
app = FastAPI(docs_url=None, redoc_url=None)

app.mount('/docs', swagger_ui())
Parameters:

  • schema_url – The URL to the OpenAPI schema.

  • csrf_cookie_name – The name of the CSRF cookie.

  • csrf_header_name – The HTTP header name which the CSRF cookie value will be added to.

  • swagger_ui_version – Which version of Swagger UI to use.