--- tags: Blue 的學習紀錄 --- # Swagger **Swagger** 是一款用於撰寫 API 文件的套件 這篇文章的目標是要紀錄在一個 **TypeScript 專案架設 Swagger** 的過程，並且簡單說明如何撰寫文件 官方網站：<https://swagger.io/> API 的文件內容，實際上就是一個 `.json` 或是 `.yaml` 而這個 `.json` 或是 `.yaml` 必須符合 OpenAPI Specification（OAS） 或是 Swagger 的規範 簡單來說，一份 API 文件實際上就是一個 `.json` 或是 `.yaml` 的檔案 而這份檔案的內容格式，必須符合 OpenAPI Specification（OAS） 或是 Swagger 在一個 TypeScript 的專案中，安裝 Swagger 相關套件的目的在於，讓 server 能夠 render 出 OpenAPI Specification（OAS） 或是 Swagger 格式的檔案，而不用自己撰寫前端程式來呈現 `.json` 或是 `.yaml` ## 環境架設 採用的套件是 swagger-ui-express npm：<https://www.npmjs.com/package/swagger-ui-express> ``` yarn add swagger-ui-express ``` 官方範例（Node.js）： ```javascript= const express = require('express'); const app = express(); const swaggerUi = require('swagger-ui-express'); const swaggerDocument = require('./swagger.json'); app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument)); ``` 如上範例，已經寫好的 API 文件透過套件即可 render 出 HTML 使用者於 `'/api-docs'` 即可查看 render 出的文件 ## 文件撰寫 文件的規範有兩種：OpenAPI Specification（OAS） 或是 Swagger 檔案的格式也有兩種：Json 或是 Yaml 寫 API 文件就是在寫 Json 或是 Yaml 可以藉由不同工具來輔助我們寫 Json 或是 Yaml - Swagger Editor <https://editor.swagger.io/> Swagger 官方的線上編輯器 ![Swagger Editor](https://blueimgur.com/iRhhj8qo63.png) 畫面左手邊編輯，右手邊呈現畫面 就和 HackMD 一樣 - VS Code 裡的 Extension - OpenAPI (Swagger) Editor <https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi> 使用方法與上面的官方線上編輯器相同 差別在於這是 VS Code 裡的 Extension，所以可以直接在 VS Code 上進行編輯與 Preview ## OpenAPI Specification <https://swagger.io/docs/specification/basic-structure/>