# fastapi_stoplight 

**Repository Path**: YueXia_1/fastapi_stoplight

## Basic Information

- **Project Name**: fastapi_stoplight 
- **Description**: FastAPI + Stoplight Elements 快速开发API文档
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 6
- **Forks**: 0
- **Created**: 2025-08-04
- **Last Updated**: 2025-10-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FastAPI Stoplight Elements

A small library that integrates Stoplight Elements into FastAPI to quickly generate a beautiful, interactive API documentation site.

## Overview

This project provides a simple function to embed Stoplight Elements in a FastAPI app, automatically rendering professional API docs from your OpenAPI schema. Stoplight Elements supports the OpenAPI specification and offers interactive "Try It" testing.

## Features

- Auto-generate OpenAPI schema from FastAPI
- Modern, elegant documentation UI
- Interactive API testing (Try It)
- Light/Dark theme toggle
- Responsive layout for different screen sizes
- Highly configurable options
- Multiple layout modes (sidebar, responsive, stacked)
- Multiple router modes

## Screenshots

- Home: `docs/PixPin_2025-08-05_00-19-23.png`
- API Detail: `docs/PixPin_2025-08-05_00-19-38.png`
- Try It: `docs/PixPin_2025-08-05_00-19-49.png`
- Dark Mode: `docs/PixPin_2025-08-05_00-23-29.png`

## Installation

From PyPI:

```bash
pip install fastapi-stoplight==0.1.0
```

Upgrade to the latest:

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

Using uv (recommended):

```bash
# Create a virtual environment (optional)
uv venv

# Add dependency to the project (writes to pyproject.toml and updates lockfile)
uv add fastapi-stoplight==0.1.0

# Upgrade to the latest version
uv add --upgrade fastapi-stoplight

# Install/sync dependencies to the virtual environment
uv sync

# Optional: run the demo without activating the venv
uv run uvicorn demo:app --host 0.0.0.0 --port 8000
```

On Windows, to manually activate the venv:

```powershell
# PowerShell
.\.venv\Scripts\Activate.ps1
```

## Quick Start

```python
from fastapi import FastAPI, Request
from pydantic import BaseModel, Field
from fastapi_stoplight import get_stoplight_elements_html

app = FastAPI()

class User(BaseModel):
    name: str = Field(..., description="User name")
    age: int = Field(..., description="Age")

@app.get("/index/{pk}", summary="Home")
def read_root(pk: str):
    return {"Hello": pk}

@app.get("/list", summary="User List", response_model=list[User])
def list_users():
    return [
        {"name": "Alice", "age": 18},
        {"name": "Bob", "age": 19},
        {"name": "Carol", "age": 20},
    ]

@app.get("/stoplight", include_in_schema=False)
def stoplight(request: Request):
    return get_stoplight_elements_html(
        openapi_url=request.app.openapi_url,
        title="User Service API"
    )

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

Visit `http://localhost:8000/stoplight` to view the generated API docs.

## Configuration Options

The `get_stoplight_elements_html` function accepts the following parameters:

- `openapi_url`: URL path to the OpenAPI spec document
- `title`: Page title
- `stoplight_elements_js_url`: CDN URL of Stoplight Elements JS
- `stoplight_elements_css_url`: CDN URL of Stoplight Elements CSS
- `stoplight_elements_favicon_url`: Favicon URL
- `api_description_document`: Raw OpenAPI document content (string)
- `base_path`: Base path of the API
- `hide_internal`: Hide content marked as internal
- `hide_try_it`: Completely hide "Try It"
- `hide_try_it_panel`: Hide the panel while keeping request examples
- `hide_schemas`: Hide schemas in the sidebar
- `hide_export`: Hide export button
- `try_it_cors_proxy`: CORS proxy URL
- `try_it_credential_policy`: Credentials policy for "Try It" (use enum `TryItCredentialsPolicy`)
- `layout`: Layout mode (use enum `DocumentationLayout`)
- `logo`: Custom logo URL
- `router`: Router mode (use enum `NavigationRouter`)

## License

MIT

## Contributing

Contributions are welcome. Please:

1. Fork the repo
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit changes (`git commit -m 'Add some AmazingFeature'`)
4. Push the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request