Stoplight Elements API Documentation Plugin for FastAPI

Installation

Install stoplight-fastapi using your preferred package manager:

Using uv (recommended)

uv add stoplight-fastapi

Using pip

pip install stoplight-fastapi

Requirements

• Python 3.10 or higher
• FastAPI 0.115.0 or higher

Quick Start

Basic Setup

from fastapi import FastAPI
from stoplight_fastapi import get_stoplight_api_reference

app = FastAPI(
  title="My API",
  description="Welcome to My Awesome API.",
  version="1.0.0",
)

@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
  """Get an item by ID."""
  return {"item_id": item_id, "q": q}

@app.get("/stoplight", include_in_schema=False)
def get_stoplight_html():
  """Render API documentation with Stoplight Elements."""
  return get_stoplight_api_reference(
    openapi_url=app.openapi_url,
    title=app.title,
  )

if __name__ == "__main__":
  import uvicorn
  uvicorn.run(app, host="0.0.0.0", port=8000)

Then visit http://localhost:8000/stoplight to view your API documentation.

Advanced Configuration

Customize the Stoplight Elements UI with advanced options:

from stoplight_fastapi import get_stoplight_api_reference, StoplightConfig

@app.get("/docs", include_in_schema=False)
def get_stoplight_html():
  """Advanced Stoplight Elements configuration."""
  return get_stoplight_api_reference(
    openapi_url=app.openapi_url,
    stoplight_config=StoplightConfig(
      router="hash",  # Enable hash-based routing for shareable links
      layout="stacked",  # Choose between 'sidebar', 'responsive', and 'stacked' layouts
      # Additional Stoplight configuration options available
    ),
  )

Live Example

uv run https://codeberg.org/naiwaaa/stoplight-fastapi/raw/branch/main/scripts/playground.py

Visit http://localhost:8000/stoplight to see Stoplight Elements in action.

Resources

• FastAPI Documentation
• Stoplight Elements Documentation