FastAPI OpenAPI customization — tags, metadata, and hiding endpoints

Default FastAPI OpenAPI docs have no descriptions, mixed endpoint groupings, and expose internal endpoints. Large APIs become hard to navigate.

Add tags, descriptions, and metadata at the router and app level. Use include_in_schema=False to hide internal endpoints. Customize the OpenAPI schema with a custom openapi() function.

from fastapi import FastAPI, APIRouter

app = FastAPI(
    title='My API',
    description='## My API\nProvides data for the app.',
    version='1.0.0',
    openapi_tags=[
        {'name': 'users', 'description': 'User management'},
        {'name': 'items', 'description': 'Item CRUD'},
    ]
)

router = APIRouter(prefix='/users', tags=['users'])

@router.get('/', summary='List all users')
async def list_users():
    return []

# Hide from docs
@app.get('/internal/health', include_in_schema=False)
async def health():
    return {'status': 'ok'}

app.include_router(router)

FastAPI generates OpenAPI 3.x JSON from route metadata. Tags group endpoints in Swagger UI. openapi_tags defines tag descriptions. include_in_schema=False excludes routes from the schema without removing them from the app.

FastAPI apps where API documentation quality matters