Skip to content

Improving API Documentation for Redocly

While the current API endpoints have the basic structure needed for Redocly (FastAPI automatically generates OpenAPI specifications), the documentation can be enhanced to provide a better experience in the Redocly-generated documentation.

Current Status

The current API endpoints have:

  • Basic route decorators with response models
  • Simple docstrings with brief descriptions
  • Proper tags for grouping endpoints
  • OpenAPI specification generation configured in the FastAPI app

To enhance the API documentation for Redocly, consider the following improvements:

1. Enhance Endpoint Docstrings

Current docstrings are minimal. Enhance them with more detailed information:

@router.get("/", response_model=List[schemas.User])
def read_users(
    db: Session = Depends(deps.get_db),
    skip: int = 0,
    limit: int = 100,
    current_user: models.User = Depends(deps.get_current_admin_user),
) -> Any:
    """
    Retrieve a list of users.

    This endpoint returns a paginated list of all users in the system.
    Only administrators can access this endpoint.

    Parameters:
    - **skip**: Number of users to skip (for pagination)
    - **limit**: Maximum number of users to return (for pagination)

    Returns:
    - List of user objects with their details (excluding passwords)
    """
    users = crud.user.get_multi(db, skip=skip, limit=limit)
    return users

2. Add Status Code Documentation

Document the possible status codes that an endpoint can return:

@router.post("/", response_model=schemas.User, status_code=201)
def create_user(
    *,
    db: Session = Depends(deps.get_db),
    user_in: schemas.UserCreate,
    current_user: models.User = Depends(deps.get_current_admin_user),
) -> Any:
    """
    Create a new user.

    This endpoint allows administrators to create new users in the system.

    Parameters:
    - **user_in**: User data including email, password, and name

    Returns:
    - Created user object with details (excluding password)

    Raises:
    - **400**: If a user with the provided email already exists
    - **401**: If the current user is not authenticated
    - **403**: If the current user is not an administrator
    """
    # ...

3. Add Examples to Pydantic Models

Add examples to your Pydantic models to show sample data:

class UserCreate(UserBase):
    email: EmailStr
    password: str

    class Config:
        schema_extra = {
            "example": {
                "email": "user@example.com",
                "password": "strongpassword123",
                "name": "John Doe",
                "is_active": True,
                "is_admin": False
            }
        }

4. Use FastAPI's Additional Parameters

FastAPI provides additional parameters for route decorators to enhance documentation:

@router.get(
    "/{user_id}",
    response_model=schemas.User,
    responses={
        200: {"description": "Successful response"},
        400: {"description": "Insufficient privileges"},
        404: {"description": "User not found"},
    },
    summary="Get User by ID",
    description="Get detailed information about a specific user by their ID.",
)
def read_user_by_id(
    user_id: int,
    current_user: models.User = Depends(deps.get_current_active_user),
    db: Session = Depends(deps.get_db),
) -> Any:
    """
    Get a specific user by id.

    This endpoint returns detailed information about a specific user.
    Users can access their own information, while administrators can access any user's information.

    Parameters:
    - **user_id**: The ID of the user to retrieve

    Returns:
    - User object with details (excluding password)
    """
    # ...

5. Add Operation IDs

Add operation IDs to make API references more developer-friendly:

@router.get(
    "/",
    response_model=List[schemas.User],
    operation_id="listUsers",
)
def read_users(...):
    # ...

This is already implemented in your code, but ensure all endpoints have appropriate tags:

api_router.include_router(users.router, prefix="/users", tags=["users"])

7. Add API Versioning and Metadata

Consider adding version information and additional metadata to your API documentation:

app = FastAPI(
    title=settings.PROJECT_NAME,
    description="API for tracker system with geospatial capabilities",
    version="1.0.0",
    openapi_url=f"{settings.API_V1_STR}/openapi.json",
    docs_url="/docs",
    redoc_url="/redoc",
    contact={
        "name": "Paul Bargewell",
        "email": "paul.bargewell@glimpseanalytics.com",
        "url": "https://github.com/Glimpse-Analytics/tracker-restapi",
    },
    license_info={
        "name": "MIT",
        "url": "https://opensource.org/licenses/MIT",
    },
)

This has already been implemented in the main.py file.

Implementation Strategy

To implement these improvements:

  1. Start with the most critical endpoints (authentication, user management)
  2. Update the Pydantic models with examples
  3. Enhance docstrings with detailed descriptions
  4. Add status code documentation
  5. Add operation IDs to endpoints

These improvements will significantly enhance the quality of the Redocly-generated documentation, making the API more accessible and easier to understand for developers.