手刻 yaml 或 json 文件讓寫 OpenAPI 文件相當不方便，透過 Swagger Editor 或 Stoplight 等 UI 輔助工具是一種選擇，但對於工程師而言，若文件與程式碼專案可以放在一起會更理想，這時就可以考慮使用 TypeSpec 撰寫。

TypeSpec 是一種用來描述 API 規格的領域特定語言 (DSL)，在 2023 年三月由前身 Cadl 正式改名為 TypeSpec，以每個月一個版本的速率釋出到現在最新版為 0.60。既然是語言而不是 UI 輔助工具，表示它擁有程式語言的特性供開發者使用，撰寫 TypeSpec 可透過編譯產出 OpenAPI，也可以將它納入程式碼庫和整合進入 CI/CD 流程，和其他的 Markdown 文件一樣成為專案的一部份。

開發環境

TypeSpec 0.60 需要 Node.js 20 環境，並透過 npm 進行安裝，IDE 的部分則提供 VS 和 VS Code 兩種擴充套件，後續將以 VS Code 進行示範。

1. 安裝環境

安裝以下項目：

• VS Code
• TypeSpec VS Code 擴充套件 及 Node.js 20

為了方便預覽撰寫出來的文件，可安裝 VS Code 擴充套件如 OpenAPI (Swagger) Editor、Redocly OpenAPI 或其他你喜歡的套件。

使用以下指令安裝 TypeSpec：

npm install -g @typespec/compiler

2. 建立 TypeSpec 專案

使用以下指令初始化專案：

tsp init

此時會詢問一些問題，範本的部分選擇「Generic REST API」，並且命名專案名稱，並安裝它所需要的 library。

使用以下指令安裝套件相依套件：

tsp install

3. 產出 OpenAPI 檔案

使用以下指令編譯專案並產出 OpenAPI 檔案：

tsp compile .

編譯完成後會看到出現 tsp-output/@typespec/openapi3/目錄，裡面有 openapi.yaml 檔案。

打開 openapi.yaml 檔，我們可以使用步驟 1. 安裝好的 OpenAPI 預覽擴充套件進行預覽，會看到一個空白的 OpenAPI 規格文件。

執行到這邊就建立好 TypeSpec 開發環境了，明天起將介紹如何撰寫 TypeSpec。