真・用 OpenAPI 打通前後端任督二脈
前一篇〈OpenAPI 打通前後端任督二脈〉介紹了 OpenAPI，以及與 OpenAPI 深度整合的 Python web 框架 FastAPI，但在前端部份，身為 Swagger 家族～祖傳～正宗～本家～嫡系～的 Swagger Client 卻不怎麼香，沒帶來多少便利性，也無法讓我們少奮鬥三十年。
直到最近又看到另外一套 openapi-typescript-codegen，用了覺得真的挺不錯的，特地撰文以資表揚。
顧名思義，openapi-typescript-codegen 會讀入 OpenAPI 定義的 API 規格，並產出一系列 TypeScript 模組，讓我們在前端專案可以方便調用。
安裝
它的安裝方式如同一般典型 JS 套件：
$ npm install openapi-typescript-codegen --save-dev
產生 OpenAPI 客戶端模組
安裝後專案內會多一個 openapi 命令可以調用，我們用它來產出 API 的 TS 模組：
$ npx openapi --input http://localhost:5000/openapi.json --output ./src/client
上面的參數應該是可以望文生義，那個來源的 openapi.json 檔案可能如下：
{
"openapi": "3.0.2",
"info": {
"title": "FastAPI",
"version": "0.1.0"
},
"servers": [
{
"url": "http://localhost:5000"
}
],
"paths": {
"/items/{item_id}": {
"get": {
"summary": "Read Item",
"description": "Read item by id.",
"operationId": "read_item",
"parameters": [
{
"required": true,
"schema": {
"title": "Item Id",
"type": "integer"
},
"name": "item_id",
"in": "path"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Item"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"delete": {
"summary": "Delete Item",
"description": "Delete item by id.",
"operationId": "delete_item",
"parameters": [
{
"required": true,
"schema": {
"title": "Item Id",
"type": "integer"
},
"name": "item_id",
"in": "path"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"HTTPValidationError": {
"title": "HTTPValidationError",
"type": "object",
"properties": {
"detail": {
"title": "Detail",
"type": "array",
"items": {
"$ref": "#/components/schemas/ValidationError"
}
}
}
},
"Item": {
"title": "Item",
"required": [
"id",
"name",
"quantity"
],
"type": "object",
"properties": {
"id": {
"title": "Id",
"type": "integer"
},
"name": {
"title": "Name",
"type": "string"
},
"quantity": {
"title": "Quantity",
"type": "integer"
}
}
},
"ValidationError": {
"title": "ValidationError",
"required": [
"loc",
"msg",
"type"
],
"type": "object",
"properties": {
"loc": {
"title": "Location",
"type": "array",
"items": {
"type": "string"
}
},
"msg": {
"title": "Message",
"type": "string"
},
"type": {
"title": "Error Type",
"type": "string"
}
}
}
}
}
}
以這份 openapi.json 為例，產生出的程式如下：
其中 core/ 是通用的請求模組，跟 API 規格有關的在 models/ 和 services/ 內，在深入他們之前我們先看 index.ts 暴露了哪些模組：
/* istanbul ignore file */
/* tslint:disable */
/* eslint-disable */
export { ApiError } from './core/ApiError';
export { CancelablePromise, CancelError } from './core/CancelablePromise';
export { OpenAPI } from './core/OpenAPI';
export type { OpenAPIConfig } from './core/OpenAPI';
export type { HTTPValidationError } from './models/HTTPValidationError';
export type { Item } from './models/Item';
export type { ValidationError } from './models/ValidationError';
export { DefaultService } from './services/DefaultService';
對照上面 Swagger UI 的資訊，DefaultService 對應的是 Swagger UI 的 Default 區塊，而 Item 這個型別定義當然也是對應到 Swagger UI 中的 Item schema 囉！
使用 OpenAPI 客戶端模組
使用上也很簡單，例如要向「Read Item」要資料：
import { DefaultService } from './client';
let itemId = 102082;
async function readItem( () => {
const response = await DefaultService.readItem( itemId );
consle.debug( response );
})
受惠於產生器和 TypeScript 完整的型別定義特性，IDE 的提示和補完機能得以滿載發揮，你幾乎不用去看 Swagger UI 就能給出該支 API 所需要的資料。
又或者要刪某筆 Item：
import { DefaultService } from './client';
let itemId = 102002;
async function deleteItem( () => {
const response = await DefaultService.deleteItem( itemId );
consle.debug( response );
})
不論是 GET、DELETE、POST、PUT 等等，都是如此這般調用，再也不用手刻 xxx 攔截器，再也不用自行二次封裝，靠 openapi-typescript-codegen 給的懶人包就能讓我們優雅的調用 API。
身份認證
要附加認證資訊當然也是可以的，OpenAPI 本身就支援好幾種 security scheme，而 openapi-typescript-codegen 則支援 HTTP Basic 認證 和 OAuth 2 的 access token 認證。
以 access token 為例，可以這麼使用：
import { OpenAPI, DefaultService } from './client';
OpenAPI.TOKEN = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
let itemId = 102082;
async function readItem( () => {
const response = await DefaultService.readItem( itemId );
consle.debug( response );
})
只要這麼一行，下面的所有交互都會自動附上該 token，蒸的很棒！
至於那 access token 該怎麼來就取決於 API 服務端的設計，如果是 OAuth 2 password flow，僅須一次交互，那也可以用產生的客戶端模組取得，如果是需要多次交互的，例如 OAuth 2 implicit flow、authorization code flow、PKCE flow 等，那就要自己動手取得囉，畢竟那些複雜的 flow 還有可能需要「前端的後端」參與，無法單靠一個前端套件搞定。
上面引入的 OpenAPI 是一個 OpenAPIConfig 型態的物件，除了可以用來配置 token 外，也可以配置發出請求時的 HTTP 標頭等參數，取決於需求運用囉！
結語
OpenAPI 已經是實質的產業標準，許多 open data 供應方都有提供 OpenAPI 文件，配合 openapi-typescript-codegen 就可以加快客端的開發腳步，而如果是自有產品，那前後端之間更是需要像 OpenAPI 這樣的橋樑建立起溝通的管道，除非你很喜歡用 Word 寫文件。
相較於在 Word 寫，直接從程式碼轉出成 OpenAPI 顯得有效率多了，後端從程式碼產生 OpenAPI 文件，前端再從 OpenAPI 文件產生程式，就像一條運作順暢的流水線，自在極意、通體舒暢。
除了 Python 的 FastAPI，其他的框架大都有內建或外掛的 OpenAPI 整合，例如 APIFlask、Strapi、Directus 等等，可以多加利用。