使用 FastAPI,你可以轻松生成和测试 API 接口文档。FastAPI 内置了自动生成文档的功能,并且提供了交互式的 API 文档界面。
以下是如何生成和测试 API 接口文档的步骤:
确保项目结构正确:
main.py
应该包含 FastAPI 应用实例和路由。run.py
应该用于启动应用。
生成和查看 API 文档:
FastAPI 自动生成两种类型的 API 文档:
- Swagger UI:在
/docs
路径。 - ReDoc:在
/redoc
路径。
- Swagger UI:在
示例代码:
main.py
:from fastapi import FastAPI from app.db.database import engine from app.db import models from app.routers import auth, caseinfo, node from logging_middleware import log_request_response # 引入日志中间件 app = FastAPI() models.Base.metadata.create_all(bind=engine) app.include_router(auth.router, prefix="/auth", tags=["auth"]) app.include_router(caseinfo.router, prefix="/caseInfo", tags=["caseInfo"]) app.include_router(node.router, prefix="/node", tags=["node"]) # 添加日志中间件 app.middleware("http")(log_request_response)
run.py
:import uvicorn if __name__ == "__main__": uvicorn.run("app.main:app", host="0.0.0.0", port=8000, reload=True, log_level="debug")
查看 API 文档:
- 启动应用程序:
python run.py
- 打开浏览器,访问以下路径查看 API 文档:
- Swagger UI:
http://localhost:8000/docs
- ReDoc:
http://localhost:8000/redoc
- Swagger UI:
- 启动应用程序:
测试 API:
- 在 Swagger UI (
/docs
) 页面中,可以看到所有定义的 API 路径、请求方法和请求/响应模型。 - 你可以直接在界面中测试 API,输入请求参数,点击“Execute”按钮发送请求并查看响应。
- 在 Swagger UI (
完整示例:
假设有一个简单的用户认证模块:
app/routers/auth.py
:from fastapi import APIRouter, Depends, HTTPException from sqlalchemy.orm import Session from app.db import schemas from app.db.database import get_db from app.services.authService import register_user, authenticate_user router = APIRouter() @router.post("/register", response_model=schemas.UserRead) def register(user: schemas.UserCreate, db: Session = Depends(get_db)): return register_user(db=db, user=user) @router.post("/login") def login(user: schemas.UserLogin, db: Session = Depends(get_db)): return authenticate_user(db=db, user=user)
app/db/schemas.py
:from pydantic import BaseModel class UserCreate(BaseModel): username: str password: str class UserLogin(BaseModel): username: str password: str class UserRead(BaseModel): id: int username: str class Config: orm_mode = True
通过这些步骤,你可以生成交互式的 API 文档,并且可以直接在文档页面中测试 API 调用,非常方便进行开发和调试。