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. Cách này dùng được cho mọi dự án FastAPI, 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 trên tài liệu — ai mở /docs cũng thấy đường đi nước bước của hệ thống. Viết tài liệu tay trong file riêng vừa tốn công, vừa nhanh lệch với code sau vài lần sửa.
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 FastAPIapp = 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_openapidef 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_schemaapp.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 osapp = 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
Áp dụng ngay cho API đang chạy: đặt title theo tên sản phẩm, version trùng version release để người dùng biết họ đang đọc tài liệu của bản nào, 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ỳ.
Bài viết liên quan
- FastAPI: viết middleware tùy chỉnh đo thời gian xử lý request và ghi log trong 5 phút
- FastAPI: cấu hình CORS đúng cách bằng CORSMiddleware trong 5 phút
- FastAPI: chặn rò rỉ password trong response bằng response_model trong 5 phút
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.
Đổi title và version có ảnh hưởng tới client sinh từ OpenAPI không?
Có, nhưng theo hướng tốt. Các công cụ sinh client đọc title và version từ schema, nên tên và phiên bản chuẩn giúp client sinh ra đúng tên package và đúng bản API. Hãy giữ version trùng với version release thật của bạn.
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.
Ghi đè app.openapi có phải viết lại toàn bộ schema không?
Không. Hàm get_openapi() sinh sẵn schema đầy đủ từ routes của bạn, bạn chỉ bổ sung hoặc sửa vài trường rồi trả về. Nhớ cache kết quả vào app.openapi_schema để mỗi request tới /openapi.json không sinh schema lại từ đầu.
💬 Bạn đã thử cách này trong dự án của mình chưa? Nếu gặp lỗi hoặc có cách làm gọn hơn, để lại bình luận bên dưới — mình đọc hết và sẽ bổ sung những ý hay vào bài.
Nguồn tham khảo
- FastAPI — Extending OpenAPI: https://fastapi.tiangolo.com/how-to/extending-openapi/
- FastAPI — Metadata and Docs URLs: https://fastapi.tiangolo.com/tutorial/metadata/
