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的安装与使用、核心技术、实际应用等方面进行了详细的阐述，并给出了实际应用的例子，希望能够对读者有所帮助。
