Swagger-自動產生API文件 (Node.js 實作+範例程式碼)

swagger

swagger 是什麼？

自動化產生互動式 API 文件，並提供 Swagger UI ，可進行測試、查看 API 相關資訊。

使用 swagger 有什麼好處？

• 提供 QA 人員所需要的參數、路徑…
• 在 Swagger UI 上立即測試，立即得到 response

以下搭配 Node.js Express 使用

1. 安裝 Swagger

npm install swagger-jsdoc --save-dev
npm install swagger-ui-express --save-dev

2. 建立 swagger.json 檔案 ( 也可以使用 YAML 格式 )

因為 JSON 格式放在這會跑版所以只放截圖，後面附上 YAML 格式

有需要可以透過 yaml to json 轉換成 JSON

JSON

• info: 紀錄整個 API 的資訊
• tags: 對 API 進行分類
• consumes、produces: API 接受的資料格式
• path: 類似 route，紀錄 api 路徑

“/users” 是我的 api 路徑

這個路徑底下有 get (後會還有 post) 方法

respones: status code 等於 200 時回傳格式紀錄在schema

"$ref”: “#/definitions/User”

在下下張圖會看到 definitions 裡面有定義 User，類似 interface 的概念

不一定要用 ref，也可以 type: “object” 之類的來定義

接著是 “/users” 路徑下的 post 方法

requestBody > content> schema 紀錄需要的參數

response

這邊分為 200 & 400 兩種

前面常常用到的 “$ref”: “#/definitions/User” 就是在這邊定義的

不想先定義的話，上面 schema 裡面的內容可改為 User 裡面的(type、properties)

YAML

openapi: 3.0.0
info:
  version: 1.0.0
  title: apple cat car
  description: User API description
tags:
- name: Users
  description: API for in the system
consumes:
- application/json
produces:
- application/json
paths:
  "/users":
    get:
      tags:
      - Users
      responses:
        '200':
          description: OK
          schema:
            "$ref": "#/definitions/User"
    post:
      tags:
      - Users
      summary: Create a new User
      requestBody:
        description: User Object
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/definitions/User"
      produces:
      - application/json
      responses:
        '200':
          description: OK
          schema:
            "$ref": "#/definitions/User"
        '400':
          description: Failed. Bad post data.
definitions:
  User:
    type: object
    properties:
      name:
        type: string
      phone:
        type: string

3. app.js 檔案中，加上下面這一段引入 Swagger 套件

‘/api-docs’ 是 Swagger UI 的路徑 ( http://localhost:3000/api-docs/ )

const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

在網頁輸入你的 Swagger UI 路徑就能看到類似以下畫面

Swagger UI

4. 完成 (以 post 這支 API 為範例)

try it out

按右邊的 「 Try it out 」

修改 User object 裡面的參數

按下藍色 Excute 執行

excute

得到 response

response

產生swagger API 文件，除了用一個 json 或是 yaml 檔案自動生成外，其實還有另一種方法

Swagger annotation （ 註釋 )

@GET({
  path: '/resource',
  description: 'Get all resources available',
  tags: ['Resources'],
  success: '#/definitions/ResourceDescription',
})
@POST({
  path: '/resource/{resourceId}',
  description: 'Update resource by ID and get its status',
  parameters: [{
  name: 'resourceId',
  description: 'Resource ID',
}],
  tags: ['Resources'],
  success: '#/definitions/ResourceStatus'
})

目前只找到 mgr-swagger-express 可以搭配 Node.js 使用，這款套件 Weekly Downloads 數量極低，加上網路上幾乎只有搭配 Java 的相關資訊，為了避免以後 debug 找不到解法，我選擇建立 swagger.json 檔案這個方法。

範例程式碼：

https://github.com/Jasmine-fe/server

參考資料:

swagger spec

swagger editor