FastAPI: tùy chỉnh tài liệu OpenAPI — đổi tiêu đề, gắn tag mô tả, ẩn endpoint nội bộ trong 5 phút
FastAPI tự sinh tài liệu Swagger UI và ReDoc từ code của bạn, nhưng mặc định nó mang tên chung chung "FastAPI" và liệt kê mọi endpoint — kể cả endpoint nội bộ không muốn ai thấy. Chỉ cần truyền title, description, version và openapi_tags vào FastAPI(), gắn tags cho từng route, và đặt include_in_schema=False cho endpoint cần ẩn là tài liệu gọn gàng, đúng thương hiệu ngay — không cần cài thêm thư viện nào.
Vấn đề
Khi mới tạo app bằng FastAPI() không tham số, trang /docs hiển thị tiêu đề "FastAPI", mô tả mặc định và version "0.1.0". Mọi endpoint xếp chung một nhóm "default" không mô tả, nên người đọc phải đoán từng route làm gì. Tệ hơn, endpoint nội bộ như /admin/stats hay /internal/health cũng xuất hiện công khai — ai mở /docs cũng thấy đường đi nước bước của hệ thống.
Giải pháp
Truyền metadata ngay lúc khởi tạo app, gắn tag cho từng route và ẩn endpoint nội bộ:
from fastapi import FastAPI
app = FastAPI(
title="Shop API",
description="API quản lý đơn hàng cho cửa hàng demo.",
version="1.2.0",
openapi_tags=[
{"name": "orders", "description": "Tạo và tra cứu đơn hàng."},
{"name": "admin", "description": "Endpoint nội bộ, chỉ dùng cho vận hành."},
],
)
@app.get("/orders", tags=["orders"])
def list_orders():
return [{"id": 1, "total": 250000}]
@app.get("/admin/stats", tags=["admin"], include_in_schema=False)
def admin_stats():
return {"orders_today": 42}
Ba tham số đầu đổi hẳn "bộ mặt" của tài liệu trên trang /docs. openapi_tags khai báo trước các nhóm kèm mô tả, còn tags=["orders"] trên decorator xếp endpoint vào đúng nhóm. include_in_schema=False chỉ ẩn endpoint khỏi schema — route vẫn chạy bình thường, chỉ không lộ trên tài liệu.
Khi cần nhiều hơn — logo công ty, URL server thật — ghi đè app.openapi bằng hàm tự viết:
from fastapi.openapi.utils import get_openapi
def custom_openapi():
if app.openapi_schema:
return app.openapi_schema
schema = get_openapi(
title=app.title,
version=app.version,
description=app.description,
routes=app.routes,
)
schema["info"]["x-logo"] = {"url": "https://example.com/logo.png"}
schema["servers"] = [
{"url": "https://api.example.com", "description": "Production"}
]
app.openapi_schema = schema
return app.openapi_schema
app.openapi = custom_openapi
get_openapi() sinh schema chuẩn như mặc định, bạn chỉ việc bổ sung trường cần thiết rồi cache lại vào app.openapi_schema để không sinh lại mỗi request.
Ở môi trường production, tắt hẳn Swagger UI và ReDoc bằng docs_url=None và redoc_url=None:
import os
app = FastAPI(
docs_url="/docs" if os.getenv("ENV") != "prod" else None,
redoc_url=None,
)
Nếu muốn khóa luôn cả file schema thì đặt thêm openapi_url=None. API vẫn chạy bình thường, chỉ không còn cửa nào để xem tài liệu công khai.
Áp dụng vào dự án của bạn
Đặt title theo tên sản phẩm, version trùng version release, và rà soát một lượt các endpoint nội bộ — health check, thống kê admin, webhook nhận từ bên thứ ba — gắn include_in_schema=False. Từ sau đó, mỗi lần thêm endpoint mới, nhớ gắn tags ngay lúc viết decorator, tài liệu sẽ tự gọn mà không cần dọn dẹp định kỳ.
Câu hỏi thường gặp
include_in_schema=False có tắt luôn endpoint không?
Không. Endpoint vẫn nhận request và trả response bình thường, chỉ biến mất khỏi file /openapi.json và khỏi trang /docs. Đây là cách ẩn tài liệu, không phải cách bảo mật — endpoint nhạy cảm vẫn cần xác thực như thường.
Có thể đổi đường dẫn /docs sang đường khác không?
Có. Truyền docs_url="/tai-lieu" khi tạo app là Swagger UI chuyển sang /tai-lieu. Tương tự, redoc_url đổi đường dẫn ReDoc và openapi_url đổi đường dẫn file schema JSON.
Đọc bản đầy đủ (tiếng Anh) tại: https://linhfish.dev/en/2026/11/19/fastapi-customize-your-openapi-docs-change-the-title-tag-endpoints-and-hide-internal-routes-in-5-minutes/
Nguồn tham khảo: FastAPI — Extending OpenAPI, FastAPI — Metadata and Docs URLs
All rights reserved