API 文件自動化（OpenAPI / Swagger）

是什麼？

OpenAPI Specification（前身是 Swagger Specification）是描述 RESTful API 的標準格式（YAML/JSON）。寫好 OpenAPI 規範檔後，可以自動生成互動式文件（Swagger UI）、客戶端 SDK、Mock Server 等。

ℹ️OpenAPI vs Swagger

OpenAPI = 規範本身（如 OpenAPI 3.1）。Swagger = 圍繞 OpenAPI 規範的工具集（Swagger UI、Swagger Editor、Swagger Codegen）。Swagger 現在是 SmartBear 公司維護的品牌名稱。

核心觀念

OpenAPI Specification：用 YAML 或 JSON 描述 API 的端點、參數、請求/回應格式、認證方式。是整個生態系的基礎
Swagger UI：根據 OpenAPI 規範自動生成的互動式網頁文件，可以直接在瀏覽器中測試 API
Code-First vs Schema-First：Code-First 從程式碼自動生成規範（如 Swashbuckle）、Schema-First 先寫規範再生成程式碼
API Client 生成：從 OpenAPI 規範自動生成各語言的客戶端 SDK（用 openapi-generator 或 NSwag）
Mock Server：從規範自動生成假的 API 伺服器，讓前端在後端還沒開發完時就能開始整合

常見誤區

⚠️常見誤區

文件和程式碼不同步：手動維護的文件很快就會過期。用 Code-First 或 CI 檢查確保同步
只寫了端點沒寫範例：沒有 Request/Response 範例的文件，開發者需要猜測格式。每個端點至少附一個完整範例
內部 API 不需要文件：即使是內部 API，三個月後你自己也會忘記參數格式。文件是給未來的自己看的

流程/步驟

選擇策略

Code-First（從程式碼生成）或 Schema-First（先寫規範）

生成/撰寫規範

產出 OpenAPI 3.x 的 YAML/JSON 檔案

設定 Swagger UI

部署互動式文件頁面，讓開發者可以測試 API

CI 整合

在 Pipeline 中驗證規範、自動發佈文件

生成客戶端

用 openapi-generator 自動生成各語言的 SDK

流程解讀：先決定用 Code-First 還是 Schema-First 策略。Code-First 適合已有程式碼的專案，Schema-First 適合 API 設計先行的團隊。生成的 OpenAPI 規範驅動 Swagger UI、SDK 生成、Mock Server 等工具鏈。CI 整合確保規範永遠和程式碼同步。

程式碼範例

C# 版本

csharp

// ASP.NET Core — Swashbuckle（Code-First）
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "My API",
        Version = "v1",
        Description = "使用者管理 API"
    });
 
    // 加入 JWT 認證支援
    options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        Description = "JWT Bearer token",
        Name = "Authorization",
        In = ParameterLocation.Header,
        Type = SecuritySchemeType.Http,
        Scheme = "bearer"
    });
 
    // 載入 XML 註解作為文件描述
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFile));
});
 
app.UseSwagger();
app.UseSwaggerUI();
 
// Controller 加上文件註解
/// <summary>
/// 取得使用者列表
/// </summary>
/// <param name="page">頁碼（從 1 開始）</param>
/// <param name="pageSize">每頁筆數（上限 100）</param>
/// <response code="200">成功回傳使用者列表</response>
[HttpGet]
[ProducesResponseType(typeof(PagedResponse<UserDto>), 200)]
public async Task<ActionResult> GetUsers(int page = 1, int pageSize = 20)
{
    // ...
}

TypeScript 版本

typescript

// Express.js — swagger-jsdoc + swagger-ui-express
import swaggerJSDoc from "swagger-jsdoc";
import swaggerUi from "swagger-ui-express";
 
const swaggerSpec = swaggerJSDoc({
  definition: {
    openapi: "3.0.0",
    info: { title: "My API", version: "1.0.0" },
    servers: [{ url: "http://localhost:3000" }],
  },
  apis: ["./routes/*.ts"], // 從 JSDoc 註解生成
});
 
app.use("/docs", swaggerUi.serve, swaggerUi.setup(swaggerSpec));
 
/**
 * @openapi
 * /api/users:
 *   get:
 *     summary: 取得使用者列表
 *     parameters:
 *       - in: query
 *         name: page
 *         schema:
 *           type: integer
 *           default: 1
 *     responses:
 *       200:
 *         description: 成功
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 data:
 *                   type: array
 *                   items:
 *                     $ref: '#/components/schemas/User'
 */
router.get("/users", getUsers);

Python 版本

python

# FastAPI — 內建 OpenAPI 支援（自動生成）
from fastapi import FastAPI
 
app = FastAPI(
    title="My API",
    version="1.0.0",
    description="使用者管理 API",
    docs_url="/docs",       # Swagger UI
    redoc_url="/redoc",     # ReDoc
)
 
@app.get(
    "/api/users",
    summary="取得使用者列表",
    response_model=PagedResponse[UserDto],
    responses={
        200: {"description": "成功回傳使用者列表"},
        401: {"description": "未認證"},
    },
)
async def get_users(page: int = 1, page_size: int = 20):
    """
    取得分頁的使用者列表。
 
    - **page**: 頁碼，從 1 開始
    - **page_size**: 每頁筆數，上限 100
    """
    return await user_service.get_paged(page, page_size)

架構圖/概念圖

Source Code

generates→

OpenAPI Spec (YAML)

renders→

Swagger UI

→

Client SDK Generator

→

Mock Server

→

CI Pipeline

Source Code 自動生成 OpenAPI Spec，這個規範檔驅動整個工具鏈：Swagger UI 提供互動式文件、SDK Generator 產出各語言客戶端、Mock Server 讓前端提前整合。CI Pipeline 驗證規範的正確性。

實戰補充

Q: Code-First 還是 Schema-First？

A: Code-First（推薦新手）：直接在程式碼中加註解，工具自動生成 OpenAPI 規範。優點是程式碼即文件，缺點是規範品質取決於程式碼品質。Schema-First：先寫 OpenAPI 規範，再生成程式碼骨架。適合 API 設計先行、多團隊協作的場景。

Q: 怎麼確保文件和程式碼永遠同步？

A: 在 CI Pipeline 中加入驗證步驟 — 從程式碼生成的規範和版控中的規範做 diff，有差異就讓 Pipeline 失敗。或直接用 Code-First 策略，文件從程式碼即時生成。

理解測驗

🤔 OpenAPI 和 Swagger 的關係是什麼？

🤔 Code-First 策略的最大優點是什麼？

🤔 為什麼即使是內部 API 也建議寫文件？

重點整理

💡一句話記住

OpenAPI 規範 = API 的單一事實來源，文件、SDK、Mock 全從這裡生成。 口訣：「Code-First 不脫節，一份規範吃到飽」

| 概念 | 說明 | |------|------| | OpenAPI Spec | YAML/JSON 格式的 API 描述標準 | | Swagger UI | 從規範自動生成的互動式文件 | | Code-First | 從程式碼生成規範，天然同步 | | Schema-First | 先寫規範再寫程式碼，設計先行 | | CI 驗證 | Pipeline 中檢查規範和程式碼一致性 |