[筆記] 六角學院 Node.js 2022 直播班記錄 – 16 Swagger 初步教學 @地瓜大的飛翔旅程

章節連結

課程相關資訊
核心概念

swagger-autogen
swagger-ui-express
swagger 的內容註解

系列文章

近期正參加六角學院的 Node.js 2022 直播班，想說做個紀錄並當作複習之用。這邊筆記下如何使用 Swagger，並產出該文件給前端使用。

請注意：本系列文章為個人對應課程的消化吸收後，所整理出來的內容。換言之，並不一定會包含全部的課程內容，也有可能會添加其他資源來說明。

核心概念

1. 有文件比沒文件好很多，Swagger 僅是一直一種方式。沒有文件形同通靈。
2. 使用 swagger-ui-express 和 swagger-autogen ( 目前建議安裝 2.5.10 )

swagger-autogen

用來生成 swagger 所需的 json 檔

const swaggerAutogen = require('swagger-autogen')()

// 關於這份文件相關的 swagger設定
const doc = {
  info: {title:"Meta API", description: "示範描述文件"},
  host: "localhost:3000" // api 所在 host
  schemes: ['http','https'] // 預設僅啟用 http, 可以用陣列傳多組值
}

const outputFile = './swagger-output.json' // 輸出路徑和檔名
const endpointFiles = ['./app.js'] // 路由進入點，像是 routes/index.js 
swaggerAutogen(outputFile, endpointFiles, doc)

const swaggerAutogen = require('swagger-autogen')()

// 關於這份文件相關的 swagger設定

const doc = {

info: {title:"Meta API", description: "示範描述文件"},

host: "localhost:3000" // api 所在 host

schemes: ['http','https'] // 預設僅啟用 http, 可以用陣列傳多組值

}

const outputFile = './swagger-output.json' // 輸出路徑和檔名

const endpointFiles = ['./app.js'] // 路由進入點，像是 routes/index.js

swaggerAutogen(outputFile, endpointFiles, doc)

swagger-ui-express

在進入點中引入此程式和方才生成的 json 檔案，並使用 app.use () 引入相關檔案即可

swagger 的內容註解

介面上的 Parameter…等資訊，是藉由在 controller 內撰寫註解來達成的

/**
    *  #swagger.tags = ['Posts']
    *  #swagger.description = '新增貼文'
    *  #swagger.parameters['body'] = {
        in: 'body',
            type: 'object',
                description: '資料格式',
                schema:{
                "$name": 'Name',
                "$content": 'This is content',
                "$userId": '627ca72879a62b5adf921bff',
                "$image": 'image'
            }
        }
    * 
    * 
    */