SwaggerUI使用教程詳解

SwaggerUI是一款優秀的API文檔生成工具，可以幫助開發人員快速生成API文檔，並且容易導入到其他平台中，從而提高了API的可閱讀性和可維護性。在本篇文章中，我們將會介紹SwaggerUI的使用詳解、核心技術、實際應用等方面。

一、SwaggerUI的安裝與使用

SwaggerUI的安裝非常簡單，可以通過兩種方式來安裝。

第一種是使用npm安裝，這個方法比較簡單。只需要通過以下命令即可：

$ npm install swagger-ui

在上述命令執行完成後，在node_modules目錄下會生成一個名為”swagger-ui”的目錄，裡面包含了所有的SwaggerUI文件。

第二種是直接下載SwaggerUI壓縮包並解壓。下載地址為：https://github.com/swagger-api/swagger-ui/releases

安裝完成後，我們需要引入SwaggerUI的相關文件，以HTML頁面為例：

<!DOCTYPE html>
<html>
   <head>
      <meta charset="UTF-8">
      <title>SwaggerUI示例</title>
      <link rel="stylesheet" type="text/css" href="./swagger-ui/dist/swagger-ui.css" />
   </head>
   <body>
      <div id="swagger-ui"></div>
      <script src="./swagger-ui/dist/swagger-ui-bundle.js" type="text/javascript"></script>
      <script src="./swagger-ui/dist/swagger-ui-standalone-preset.js" type="text/javascript"></script>
      <script type="text/javascript">
          window.onload = function() {
             // 填寫swagger.json的地址
             const ui = SwaggerUIBundle({
                url: "https://petstore.swagger.io/v2/swagger.json",
                dom_id: '#swagger-ui',
                presets: [
                  SwaggerUIBundle.presets.apis,
                  SwaggerUIStandalonePreset
                ],
                layout: "StandaloneLayout"
             })
          }
      </script>
   </body>
</html>

在上述代碼中，我們首先引入了SwaggerUI的CSS樣式文件和兩個JS文件。其中CSS文件用於美化SwaggerUI界面，後兩個JS文件包含了SwggerUI所需的核心代碼。

在HTML代碼中，我們添加了一個

二、SwaggerUI的核心技術

1. SwaggerUI的配置

SwaggerUI的配置參數為一個對象，包含了SwaggerUI的配置信息、樣式設置等。在上述代碼中，我們通過url參數指定了swagger.json的地址，通過dom_id參數指定了SwaggerUI的UI容器。

另外，在UI容器中還有一些參數可以設置，比如title、description、termsOfService等。我們可以通過以下代碼來進行設置：

const ui = SwaggerUIBundle({
   url: "https://petstore.swagger.io/v2/swagger.json",
   dom_id: '#swagger-ui',
   presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
   ],
   layout: "StandaloneLayout",
   // 設置title、description、termsOfService
   config: {
      title: "SwaggerUI示例",
      description: "SwaggerUI使用教程詳解",
      termsOfService: "https://github.com/swagger-api/swagger-ui/blob/master/LICENSE"
   }
})

2. SwaggerUI的主題設置

SwaggerUI支持自定義主題，並且提供了一個主題編輯器，藉助這個工具我們可以方便地生成自己的主題。具體步驟如下：

訪問主題編輯器：https://labsyspharm.github.io/swagger-ui-themes/
選擇、調整主題參數
點擊Generate按鈕生成主題CSS文件
將生成的CSS文件引入到HTML頁面中
創建一個SwaggerUI實例時，在配置參數中添加theme參數

例如，我們可以通過以下代碼來創建一個紅色主題的SwaggerUI實例：

const ui = SwaggerUIBundle({
   url: "https://petstore.swagger.io/v2/swagger.json",
   dom_id: '#swagger-ui',
   theme: 'red',
   presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
   ],
   layout: "StandaloneLayout",
})

三、SwaggerUI的實際應用

在實際應用中，SwaggerUI可以幫助我們快速生成API文檔，並且可以通過Swagger Editor進行編輯、校驗。除此之外，SwaggerUI還可以和各種後端語言和框架集成，具體的步驟如下：

使用Swagger Editor編輯並生成swagger.json文件
將swagger.json文件放到後端項目目錄下
在後端項目中使用Swagger/OpenAPI代碼生成工具生成API介面函數
將API介面函數添加到後端代碼中
啟動後端項目，並訪問SwaggerUI UI界面
在SwaggerUI中測試API介面函數

下面，我們以Node.js和Express框架為例，演示如何利用SwaggerUI生成和測試API：

步驟一：安裝SwaggerUI和Express

$ npm install express
$ npm install swagger-ui

步驟二：編輯swagger.json文件

在Swagger Editor中編輯swagger.json文件。具體操作如下：

訪問Swagger Editor：https://editor.swagger.io/
編輯swagger.json文件
生成swagger.json文件

下面是一個swagger.json的示例：

{
  "swagger": "2.0",
  "info": {
    "title": "Node.js與Express演示介面",
    "version": "1.0.0"
  },
  "paths": {
    "/": {
      "get": {
        "operationId": "getRoot",
        "responses": {
          "200": {
            "description": "操作成功",
            "schema": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

步驟三：生成API介面函數

在終端中輸入以下命令：

$ npx swagger-jsdoc -d swagger.json -o swagger.js

上述命令會在當前目錄下生成一個名為swagger.js的文件，其中包含了API介面函數的定義。下面是swagger.js的示例代碼：

const express = require("express")
const swaggerUi = require("swagger-ui-express")
const swaggerJsdoc = require("swagger-jsdoc")

const app = express()
const port = 3000

// 定義伺服器配置
const options = {
  definition: {
    openapi: "3.0.0",
    info: {
      title: "Node.js與Express演示介面",
      version: "1.0.0",
    },
  },

  // API文件路徑
  apis: ["./swagger.js"],
}

const specs = swaggerJsdoc(options)

// 設置中間件
app.use("/docs", swaggerUi.serve)
app.get(
  "/docs",
  swaggerUi.setup(specs, {
    explorer: true,
  })
)

app.listen(port, () => {
  console.log(`Example app listening at http://localhost:${port}`)
})

// API介面函數
/**
 * @swagger
 * /:
 *   get:
 *     description: 獲取根路徑
 *     responses:
 *       200:
 *         description: 成功
 *         content:
 *           application/json:
 *             schema:
 *               type: string
 */
app.get("/", (req, res) => {
  res.send("Hello World!")
})

可以看到，在swagger.js文件中，我們定義了API介面函數，並添加了Swagger注釋。這個注釋包含了該API的請求方法、路徑、描述、參數、返回值等信息。

步驟四：啟動伺服器

在終端中輸入以下命令：

$ node app.js

可以看到，在SwaggerUI中會顯示我們定義的API介面函數。點擊API方法名稱，即可在SwaggerUI中測試API介面函數。

四、總結

SwaggerUI是一款優秀的API文檔生成工具，可以幫助開發人員快速生成API文檔，並且容易導入到其他平台中，從而提高了API的可閱讀性和可維護性。本篇文章針對SwaggerUI的安裝與使用、核心技術、實際應用等方面進行了詳細的闡述，並給出了實際應用的例子，希望能夠對讀者有所幫助。

原創文章，作者：小藍，如若轉載，請註明出處：https://www.506064.com/zh-tw/n/198774.html