API Documentation with Redocly

This project uses Redocly to generate interactive API documentation from the OpenAPI specification. Redocly provides a clean, responsive, and customizable interface for exploring the API endpoints, request/response schemas, and authentication requirements.

Enhanced API Documentation

The API documentation has been enhanced with:

Detailed metadata about the API (version, description, contact information, license)
Improved endpoint descriptions and parameter documentation
Response status code documentation
Type annotations for better schema generation

For more information on how to further improve the API documentation, see the Improving API Docs page.

Viewing the API Documentation

The API documentation is available at the following locations:

In the documentation site: Navigate to the "API Reference" section and click on "API Documentation"
Directly from the API: Visit /docs when the API is running (FastAPI's Swagger UI)
Redocly standalone page: Available at /redoc when the API is running (FastAPI's ReDoc UI)

Generating the API Documentation

The API documentation is generated from the OpenAPI specification, which is automatically created by FastAPI. To update the documentation:

Make sure the API is running:

docker-compose up -d api

Export the OpenAPI specification:

python scripts/export_openapi.py

Build the Redocly documentation:
```
./scripts/build_redoc.sh
```

Alternatively, you can use the redoc service in Docker Compose:

docker-compose up redoc

Customizing the Documentation

The Redocly documentation can be customized by modifying the redocly.yaml configuration file. This file controls the appearance, behavior, and validation rules for the API documentation.

Some common customizations include:

Changing the theme colors
Adding a logo
Customizing the navigation
Setting validation rules for the OpenAPI specification

For more information on customizing Redocly, see the Redocly documentation.

OpenAPI Specification

The OpenAPI specification is the source of truth for the API documentation. It is automatically generated by FastAPI based on the API routes, request/response models, and docstrings.

To improve the documentation:

Add detailed docstrings to your API routes
Use Pydantic models for request and response schemas
Include examples in your Pydantic models
Add tags to group related endpoints

Example of a well-documented API route:

@router.post("/items/", response_model=schemas.Item, tags=["items"])
def create_item(
    item: schemas.ItemCreate,
    current_user: models.User = Depends(deps.get_current_active_user),
) -> Any:
    """
    Create a new item.

    This endpoint allows authenticated users to create a new item.
    The item will be associated with the current user.

    - **name**: The name of the item (required)
    - **description**: A detailed description of the item (optional)
    - **price**: The price of the item (required)
    - **tax**: The tax rate for the item (optional)
    """
    return crud.item.create_with_owner(db=db, obj_in=item, owner_id=current_user.id)