Metadata-Version: 2.4
Name: stoplight-fastapi
Version: 0.1.0
Summary: Seamlessly integrate Stoplight Elements for beautiful, interactive API documentation in FastAPI.
Keywords: fastapi,api,documentation,stoplight,openapi,interactive-docs,api-docs,rest-api,swagger
Author: Tho Nguyen
Author-email: Tho Nguyen <contact@naiwaaa.simplelogin.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: fastapi>=0.115.0
Requires-Python: >=3.10
Project-URL: Homepage, https://codeberg.org/naiwaaa/stoplight-fastapi
Project-URL: Documentation, https://codeberg.org/naiwaaa/stoplight-fastapi
Project-URL: Repository, https://codeberg.org/naiwaaa/stoplight-fastapi
Project-URL: Issues, https://codeberg.org/naiwaaa/stoplight-fastapi/issues
Description-Content-Type: text/markdown

# Stoplight Elements API Documentation Plugin for FastAPI

[![Package - Version](https://img.shields.io/pypi/v/stoplight-fastapi)](https://pypi.python.org/pypi/stoplight-fastapi)
[![Package - Supported Python Versions](https://img.shields.io/pypi/pyversions/stoplight-fastapi)](https://codeberg.org/naiwaaa/stoplight-fastapi)
[![Package - License](https://img.shields.io/pypi/l/stoplight-fastapi)](https://codeberg.org/naiwaaa/stoplight-fastapi/src/branch/main/LICENSE)

## Installation

Install `stoplight-fastapi` using your preferred package manager:

### Using uv (recommended)

```bash
uv add stoplight-fastapi
```

### Using pip

```bash
pip install stoplight-fastapi
```

### Requirements

- Python 3.10 or higher
- FastAPI 0.115.0 or higher

## Quick Start

### Basic Setup

```python
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](https://docs.stoplight.io/docs/elements/b074dc47b2826-elements-configuration-options):

```python
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

![demo](https://codeberg.org/naiwaaa/stoplight-fastapi/raw/branch/main/assets/screenshot.png)

```bash
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](https://fastapi.tiangolo.com)
- [Stoplight Elements Documentation](https://docs.stoplight.io/docs/elements/d6a8ba3f3c186-stoplight-elements)
