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/n/198774.html