手把手教你Swagger UI界面搭建步骤从环境准备到项目集成再到优化配置全面指南构建专业API文档平台

威震华夏关云长

Swagger UI是一个强大的工具，它允许我们可视化地展示和交互API文档。通过Swagger UI，开发人员可以轻松地理解和测试API，而无需查看实际的代码实现。本文将详细介绍如何从零开始搭建Swagger UI界面，包括环境准备、项目集成、基本配置以及优化配置，帮助您构建一个专业的API文档平台。

1. 环境准备

在开始搭建Swagger UI之前，我们需要准备一些必要的工具和环境。

1.1 必要工具

• Java开发工具包（JDK）8或更高版本（如果使用Java）
• Node.js和npm（如果使用JavaScript）
• 一个IDE（如IntelliJ IDEA、VS Code等）
• Maven或Gradle（如果使用Java）

1.2 项目结构

我们将创建一个基本的项目结构，以便集成Swagger UI。这里以Spring Boot项目为例：

2. swagger-demo
3. ├── src
4. │   ├── main
5. │   │   ├── java
6. │   │   │   └── com
7. │   │   │       └── example
8. │   │   │           └── swagger
9. │   │   │               ├── SwaggerDemoApplication.java
10. │   │   │               ├── controller
11. │   │   │               │   └── UserController.java
12. │   │   │               ├── model
13. │   │   │               │   └── User.java
14. │   │   │               └── config
15. │   │   │                   └── SwaggerConfig.java
16. │   │   └── resources
17. │   │       └── application.properties
18. │   └── test
19. │       └── java
20. └── pom.xml

复制代码

2. 项目集成

Swagger UI可以与多种编程语言和框架集成。下面我们将介绍几种常见的集成方式。

2.1 Spring Boot项目集成

首先，我们需要在pom.xml文件中添加Swagger相关的依赖：

2. <dependencies>
3.     <!-- Spring Boot Starter Web -->
4.     <dependency>
5.         <groupId>org.springframework.boot</groupId>
6.         <artifactId>spring-boot-starter-web</artifactId>
7.     </dependency>
8.    
9.     <!-- Swagger2 -->
10.     <dependency>
11.         <groupId>io.springfox</groupId>
12.         <artifactId>springfox-swagger2</artifactId>
13.         <version>3.0.0</version>
14.     </dependency>
15.    
16.     <!-- Swagger UI -->
17.     <dependency>
18.         <groupId>io.springfox</groupId>
19.         <artifactId>springfox-swagger-ui</artifactId>
20.         <version>3.0.0</version>
21.     </dependency>
22.    
23.     <!-- Springfox Boot Starter (可选，简化配置) -->
24.     <dependency>
25.         <groupId>io.springfox</groupId>
26.         <artifactId>springfox-boot-starter</artifactId>
27.         <version>3.0.0</version>
28.     </dependency>
29. </dependencies>

复制代码

接下来，我们创建一个Swagger配置类：

2. package com.example.swagger.config;
4. import org.springframework.context.annotation.Bean;
5. import org.springframework.context.annotation.Configuration;
6. import springfox.documentation.builders.ApiInfoBuilder;
7. import springfox.documentation.builders.PathSelectors;
8. import springfox.documentation.builders.RequestHandlerSelectors;
9. import springfox.documentation.service.ApiInfo;
10. import springfox.documentation.service.Contact;
11. import springfox.documentation.spi.DocumentationType;
12. import springfox.documentation.spring.web.plugins.Docket;
14. @Configuration
15. public class SwaggerConfig {
17.     @Bean
18.     public Docket api() {
19.         return new Docket(DocumentationType.SWAGGER_2)
20.                 .select()
21.                 .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
22.                 .paths(PathSelectors.any())
23.                 .build()
24.                 .apiInfo(apiInfo());
25.     }
27.     private ApiInfo apiInfo() {
28.         return new ApiInfoBuilder()
29.                 .title("Swagger Demo API")
30.                 .description("This is a demo API for Swagger UI")
31.                 .version("1.0.0")
32.                 .contact(new Contact("Your Name", "https://example.com", "your.email@example.com"))
33.                 .build();
34.     }
35. }

复制代码

在Spring Boot主应用程序类上添加@EnableSwagger2注解：

2. package com.example.swagger;
4. import org.springframework.boot.SpringApplication;
5. import org.springframework.boot.autoconfigure.SpringBootApplication;
6. import springfox.documentation.swagger2.annotations.EnableSwagger2;
8. @SpringBootApplication
9. @EnableSwagger2
10. public class SwaggerDemoApplication {
12.     public static void main(String[] args) {
13.         SpringApplication.run(SwaggerDemoApplication.class, args);
14.     }
15. }

复制代码

创建一个简单的用户控制器和模型：

2. package com.example.swagger.model;
4. public class User {
5.     private Long id;
6.     private String username;
7.     private String email;
8.    
9.     // 构造函数、getter和setter方法
10.     public User() {}
11.    
12.     public User(Long id, String username, String email) {
13.         this.id = id;
14.         this.username = username;
15.         this.email = email;
16.     }
17.    
18.     public Long getId() {
19.         return id;
20.     }
21.    
22.     public void setId(Long id) {
23.         this.id = id;
24.     }
25.    
26.     public String getUsername() {
27.         return username;
28.     }
29.    
30.     public void setUsername(String username) {
31.         this.username = username;
32.     }
33.    
34.     public String getEmail() {
35.         return email;
36.     }
37.    
38.     public void setEmail(String email) {
39.         this.email = email;
40.     }
41. }

复制代码

2. package com.example.swagger.controller;
4. import com.example.swagger.model.User;
5. import io.swagger.annotations.Api;
6. import io.swagger.annotations.ApiOperation;
7. import io.swagger.annotations.ApiParam;
8. import org.springframework.web.bind.annotation.*;
10. import java.util.ArrayList;
11. import java.util.List;
12. import java.util.concurrent.ConcurrentHashMap;
13. import java.util.concurrent.ConcurrentMap;
14. import java.util.concurrent.atomic.AtomicLong;
16. @RestController
17. @RequestMapping("/api/users")
18. @Api(tags = "User Management API")
19. public class UserController {
21.     private final ConcurrentMap<Long, User> users = new ConcurrentHashMap<>();
22.     private final AtomicLong counter = new AtomicLong();
24.     @GetMapping
25.     @ApiOperation(value = "Get all users", notes = "Retrieve a list of all users")
26.     public List<User> getAllUsers() {
27.         return new ArrayList<>(users.values());
28.     }
30.     @GetMapping("/{id}")
31.     @ApiOperation(value = "Get user by ID", notes = "Retrieve a user by their ID")
32.     public User getUserById(
33.             @ApiParam(value = "User ID", required = true) @PathVariable Long id) {
34.         return users.get(id);
35.     }
37.     @PostMapping
38.     @ApiOperation(value = "Create a new user", notes = "Add a new user to the system")
39.     public User createUser(
40.             @ApiParam(value = "User object", required = true) @RequestBody User user) {
41.         Long id = counter.incrementAndGet();
42.         user.setId(id);
43.         users.put(id, user);
44.         return user;
45.     }
47.     @PutMapping("/{id}")
48.     @ApiOperation(value = "Update an existing user", notes = "Update the details of an existing user")
49.     public User updateUser(
50.             @ApiParam(value = "User ID", required = true) @PathVariable Long id,
51.             @ApiParam(value = "Updated user object", required = true) @RequestBody User user) {
52.         user.setId(id);
53.         users.put(id, user);
54.         return user;
55.     }
57.     @DeleteMapping("/{id}")
58.     @ApiOperation(value = "Delete a user", notes = "Remove a user from the system")
59.     public void deleteUser(
60.             @ApiParam(value = "User ID", required = true) @PathVariable Long id) {
61.         users.remove(id);
62.     }
63. }

复制代码

现在，我们可以运行Spring Boot应用程序，并访问Swagger UI界面。默认情况下，Swagger UI可以通过以下URL访问：

2. http://localhost:8080/swagger-ui.html

复制代码

2.2 Node.js项目集成

首先，创建一个新的Node.js项目并安装必要的依赖：

2. mkdir swagger-node-demo
3. cd swagger-node-demo
4. npm init -y
5. npm install express swagger-ui-express swagger-jsdoc

复制代码

创建一个index.js文件，并设置基本的Express应用：

2. const express = require('express');
3. const swaggerUi = require('swagger-ui-express');
4. const swaggerJsdoc = require('swagger-jsdoc');
6. const app = express();
7. app.use(express.json());
9. // Swagger configuration
10. const options = {
11.   definition: {
12.     openapi: '3.0.0',
13.     info: {
14.       title: 'Node.js Swagger API',
15.       version: '1.0.0',
16.       description: 'A demo API for Swagger UI in Node.js',
17.     },
18.     servers: [
19.       {
20.         url: 'http://localhost:3000',
21.       },
22.     ],
23.   },
24.   apis: ['./index.js'], // files containing annotations as above
25. };
27. const specs = swaggerJsdoc(options);
28. app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));
30. // User data storage
31. let users = [];
32. let idCounter = 1;
34. /**
35. * @swagger
36. * components:
37. *   schemas:
38. *     User:
39. *       type: object
40. *       required:
41. *         - username
42. *         - email
43. *       properties:
44. *         id:
45. *           type: integer
46. *           description: The user ID
47. *         username:
48. *           type: string
49. *           description: The user's username
50. *         email:
51. *           type: string
52. *           description: The user's email
53. *       example:
54. *         id: 1
55. *         username: johndoe
56. *         email: john@example.com
57. */
59. /**
60. * @swagger
61. * /users:
62. *   get:
63. *     summary: Get all users
64. *     description: Retrieve a list of all users
65. *     responses:
66. *       200:
67. *         description: A list of users
68. *         content:
69. *           application/json:
70. *             schema:
71. *               type: array
72. *               items:
73. *                 $ref: '#/components/schemas/User'
74. */
75. app.get('/users', (req, res) => {
76.   res.json(users);
77. });
79. /**
80. * @swagger
81. * /users/{id}:
82. *   get:
83. *     summary: Get user by ID
84. *     description: Retrieve a user by their ID
85. *     parameters:
86. *       - in: path
87. *         name: id
88. *         required: true
89. *         description: User ID
90. *         schema:
91. *           type: integer
92. *     responses:
93. *       200:
94. *         description: A single user
95. *         content:
96. *           application/json:
97. *             schema:
98. *               $ref: '#/components/schemas/User'
99. *       404:
100. *         description: User not found
101. */
102. app.get('/users/:id', (req, res) => {
103.   const id = parseInt(req.params.id);
104.   const user = users.find(u => u.id === id);
105.   if (user) {
106.     res.json(user);
107.   } else {
108.     res.status(404).json({ message: 'User not found' });
109.   }
110. });
112. /**
113. * @swagger
114. * /users:
115. *   post:
116. *     summary: Create a new user
117. *     description: Add a new user to the system
118. *     requestBody:
119. *       required: true
120. *       content:
121. *         application/json:
122. *           schema:
123. *             $ref: '#/components/schemas/User'
124. *     responses:
125. *       201:
126. *         description: User created successfully
127. *         content:
128. *           application/json:
129. *             schema:
130. *               $ref: '#/components/schemas/User'
131. */
132. app.post('/users', (req, res) => {
133.   const { username, email } = req.body;
134.   const newUser = {
135.     id: idCounter++,
136.     username,
137.     email
138.   };
139.   users.push(newUser);
140.   res.status(201).json(newUser);
141. });
143. /**
144. * @swagger
145. * /users/{id}:
146. *   put:
147. *     summary: Update an existing user
148. *     description: Update the details of an existing user
149. *     parameters:
150. *       - in: path
151. *         name: id
152. *         required: true
153. *         description: User ID
154. *         schema:
155. *           type: integer
156. *     requestBody:
157. *       required: true
158. *       content:
159. *         application/json:
160. *           schema:
161. *             $ref: '#/components/schemas/User'
162. *     responses:
163. *       200:
164. *         description: User updated successfully
165. *         content:
166. *           application/json:
167. *             schema:
168. *               $ref: '#/components/schemas/User'
169. *       404:
170. *         description: User not found
171. */
172. app.put('/users/:id', (req, res) => {
173.   const id = parseInt(req.params.id);
174.   const { username, email } = req.body;
175.   const userIndex = users.findIndex(u => u.id === id);
176.   
177.   if (userIndex !== -1) {
178.     users[userIndex] = { id, username, email };
179.     res.json(users[userIndex]);
180.   } else {
181.     res.status(404).json({ message: 'User not found' });
182.   }
183. });
185. /**
186. * @swagger
187. * /users/{id}:
188. *   delete:
189. *     summary: Delete a user
190. *     description: Remove a user from the system
191. *     parameters:
192. *       - in: path
193. *         name: id
194. *         required: true
195. *         description: User ID
196. *         schema:
197. *           type: integer
198. *     responses:
199. *       200:
200. *         description: User deleted successfully
201. *       404:
202. *         description: User not found
203. */
204. app.delete('/users/:id', (req, res) => {
205.   const id = parseInt(req.params.id);
206.   const userIndex = users.findIndex(u => u.id === id);
207.   
208.   if (userIndex !== -1) {
209.     users.splice(userIndex, 1);
210.     res.json({ message: 'User deleted successfully' });
211.   } else {
212.     res.status(404).json({ message: 'User not found' });
213.   }
214. });
216. const PORT = process.env.PORT || 3000;
217. app.listen(PORT, () => {
218.   console.log(`Server is running on port ${PORT}`);
219. });

复制代码

运行Node.js应用程序：

2. node index.js

复制代码

然后，访问Swagger UI界面：

2. http://localhost:3000/api-docs

复制代码

3. 基本配置

Swagger UI提供了许多配置选项，可以根据需要进行自定义。下面我们将介绍一些基本的配置方法。

3.1 Spring Boot中的基本配置

在Swagger配置类中，我们可以配置API的基本信息：

2. private ApiInfo apiInfo() {
3.     return new ApiInfoBuilder()
4.             .title("API Documentation")
5.             .description("This is the API documentation for our service")
6.             .version("1.0.0")
7.             .contact(new Contact("Developer Name", "https://example.com", "developer@example.com"))
8.             .license("Apache License Version 2.0")
9.             .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0")
10.             .build();
11. }

复制代码

Docket是Swagger的核心配置类，我们可以通过它来配置Swagger的各种选项：

2. @Bean
3. public Docket api() {
4.     return new Docket(DocumentationType.SWAGGER_2)
5.             .select()
6.             .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
7.             .paths(PathSelectors.any())
8.             .build()
9.             .apiInfo(apiInfo())
10.             .securitySchemes(Arrays.asList(apiKey()))
11.             .securityContexts(Arrays.asList(securityContext()))
12.             .produces(Collections.singleton("application/json"))
13.             .consumes(Collections.singleton("application/json"));
14. }

复制代码

如果API需要密钥认证，我们可以配置如下：

2. private ApiKey apiKey() {
3.     return new ApiKey("JWT", "Authorization", "header");
4. }
6. private SecurityContext securityContext() {
7.     return SecurityContext.builder()
8.             .securityReferences(defaultAuth())
9.             .forPaths(PathSelectors.regex("/api/.*"))
10.             .build();
11. }
13. private List<SecurityReference> defaultAuth() {
14.     AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
15.     AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
16.     authorizationScopes[0] = authorizationScope;
17.     return Arrays.asList(new SecurityReference("JWT", authorizationScopes));
18. }

复制代码

3.2 Node.js中的基本配置

在Node.js中，我们可以通过swagger-jsdoc的选项来配置OpenAPI规范：

2. const options = {
3.   definition: {
4.     openapi: '3.0.0',
5.     info: {
6.       title: 'Node.js Swagger API',
7.       version: '1.0.0',
8.       description: 'A demo API for Swagger UI in Node.js',
9.       contact: {
10.         name: 'API Support',
11.         url: 'https://example.com/support',
12.         email: 'support@example.com'
13.       },
14.       license: {
15.         name: 'Apache 2.0',
16.         url: 'https://www.apache.org/licenses/LICENSE-2.0.html'
17.       }
18.     },
19.     servers: [
20.       {
21.         url: 'http://localhost:3000',
22.         description: 'Development server'
23.       }
24.     ],
25.     components: {
26.       securitySchemes: {
27.         bearerAuth: {
28.           type: 'http',
29.           scheme: 'bearer',
30.           bearerFormat: 'JWT'
31.         }
32.       }
33.     },
34.     security: [
35.       {
36.         bearerAuth: []
37.       }
38.     ]
39.   },
40.   apis: ['./index.js']
41. };

复制代码

我们还可以配置Swagger UI的显示选项：

2. const swaggerOptions = {
3.   customCss: '.swagger-ui .topbar { display: none }',
4.   customSiteTitle: "My API Documentation"
5. };
7. app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs, swaggerOptions));

复制代码

4. 高级配置

除了基本配置外，Swagger UI还提供了许多高级配置选项，可以帮助我们更好地展示和管理API文档。

4.1 Spring Boot中的高级配置

如果项目中有多个模块或不同版本的API，我们可以将它们分组显示：

2. @Bean
3. public Docket publicApi() {
4.     return new Docket(DocumentationType.SWAGGER_2)
5.             .select()
6.             .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller.public"))
7.             .paths(PathSelectors.any())
8.             .build()
9.             .groupName("public")
10.             .apiInfo(publicApiInfo());
11. }
13. @Bean
14. public Docket privateApi() {
15.     return new Docket(DocumentationType.SWAGGER_2)
16.             .select()
17.             .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller.private"))
18.             .paths(PathSelectors.any())
19.             .build()
20.             .groupName("private")
21.             .apiInfo(privateApiInfo());
22. }
24. private ApiInfo publicApiInfo() {
25.     return new ApiInfoBuilder()
26.             .title("Public API Documentation")
27.             .description("This is the public API documentation")
28.             .version("1.0.0")
29.             .build();
30. }
32. private ApiInfo privateApiInfo() {
33.     return new ApiInfoBuilder()
34.             .title("Private API Documentation")
35.             .description("This is the private API documentation")
36.             .version("1.0.0")
37.             .build();
38. }

复制代码

我们可以通过注解来自定义模型属性的显示：

2. package com.example.swagger.model;
4. import io.swagger.annotations.ApiModel;
5. import io.swagger.annotations.ApiModelProperty;
7. @ApiModel(description = "User details")
8. public class User {
9.     @ApiModelProperty(notes = "The database generated user ID", required = true, example = "1")
10.     private Long id;
11.    
12.     @ApiModelProperty(notes = "The user's username", required = true, example = "johndoe")
13.     private String username;
14.    
15.     @ApiModelProperty(notes = "The user's email address", required = true, example = "john@example.com")
16.     private String email;
17.    
18.     // 构造函数、getter和setter方法
19.     // ...
20. }

复制代码

如果我们不想在Swagger UI中显示某些端点，可以使用@ApiIgnore注解：

2. @ApiIgnore
3. @RestController
4. @RequestMapping("/internal")
5. public class InternalController {
6.     // Controller methods
7. }

复制代码

或者在Docket配置中排除某些路径：

2. @Bean
3. public Docket api() {
4.     return new Docket(DocumentationType.SWAGGER_2)
5.             .select()
6.             .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
7.             .paths(PathSelectors.regex("(?!/internal/.*").and(PathSelectors.any()))
8.             .build()
9.             .apiInfo(apiInfo());
10. }

复制代码

4.2 Node.js中的高级配置

我们可以使用外部的Swagger/OpenAPI文件，而不是在代码中定义：

2. const fs = require('fs');
3. const path = require('path');
5. // Read external swagger.json file
6. const swaggerDocument = JSON.parse(fs.readFileSync(path.join(__dirname, 'swagger.json'), 'utf8'));
8. // Serve Swagger UI
9. app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

复制代码

如果我们有多个Swagger文档，可以分别配置：

2. // First API documentation
3. const options1 = {
4.   definition: {
5.     openapi: '3.0.0',
6.     info: {
7.       title: 'API v1',
8.       version: '1.0.0',
9.     },
10.   },
11.   apis: ['./routes/v1/*.js'],
12. };
13. const specs1 = swaggerJsdoc(options1);
15. // Second API documentation
16. const options2 = {
17.   definition: {
18.     openapi: '3.0.0',
19.     info: {
20.       title: 'API v2',
21.       version: '2.0.0',
22.     },
23.   },
24.   apis: ['./routes/v2/*.js'],
25. };
26. const specs2 = swaggerJsdoc(options2);
28. // Serve both Swagger UIs
29. app.use('/api-docs/v1', swaggerUi.serve, swaggerUi.setup(specs1));
30. app.use('/api-docs/v2', swaggerUi.serve, swaggerUi.setup(specs2));

复制代码

我们可以使用Swagger插件来扩展功能：

2. const swaggerUi = require('swagger-ui-express');
3. const swaggerJsdoc = require('swagger-jsdoc');
4. const { swaggerUiServeFiles, swaggerUiSetup } = require('swagger-ui-dist');
6. // Use custom plugins
7. const customOptions = {
8.   explorer: true,
9.   customCss: '.swagger-ui .topbar { display: none }',
10.   customSiteTitle: "My Custom API Docs",
11.   plugins: [
12.     function(system) {
13.       return {
14.         components: {
15.           Topbar: function() { return null } // Disable top bar
16.         }
17.       }
18.     }
19.   ]
20. };
22. app.use('/api-docs', swaggerUiServeFiles, swaggerUiSetup(specs, customOptions));

复制代码

5. 自定义UI

Swagger UI提供了多种自定义选项，可以根据品牌或个人喜好来调整界面。

5.1 自定义CSS

我们可以通过添加自定义CSS来改变Swagger UI的外观：

在Spring Boot中，我们可以创建一个自定义的CSS文件，并在SwaggerConfig中引用它：

2. @Bean
3. public Docket api() {
4.     return new Docket(DocumentationType.SWAGGER_2)
5.             // ...
6.             .securityContexts(Arrays.asList(securityContext()))
7.             .produces(Collections.singleton("application/json"))
8.             .consumes(Collections.singleton("application/json"));
9. }
11. // Add a custom CSS file
12. @Bean
13. public UiConfiguration uiConfig() {
14.     return UiConfigurationBuilder.builder()
15.             .deepLinking(true)
16.             .displayOperationId(false)
17.             .defaultModelsExpandDepth(1)
18.             .defaultModelExpandDepth(1)
19.             .defaultModelRendering(ModelRendering.EXAMPLE)
20.             .displayRequestDuration(false)
21.             .docExpansion(DocExpansion.NONE)
22.             .filter(false)
23.             .maxDisplayedTags(null)
24.             .operationsSorter(OperationsSorter.ALPHA)
25.             .showExtensions(false)
26.             .tagsSorter(TagsSorter.ALPHA)
27.             .validatorUrl(null)
28.             .build();
29. }

复制代码

然后，在src/main/resources/static目录下创建一个swagger.css文件：

2. .swagger-ui .topbar {
3.     display: none;
4. }
6. .swagger-ui .info {
7.     margin: 50px 0;
8. }
10. .swagger-ui .info .title {
11.     color: #3b4151;
12.     font-family: sans-serif;
13.     font-size: 36px;
14. }
16. .swagger-ui .info .description {
17.     color: #3b4151;
18.     font-family: sans-serif;
19. }
21. .swagger-ui .opblock .opblock-summary-description {
22.     font-family: sans-serif;
23.     color: #3b4151;
24. }

复制代码

在Node.js中，我们可以直接在配置中添加自定义CSS：

2. const customCss = `
3. .swagger-ui .topbar {
4.     display: none;
5. }
7. .swagger-ui .info {
8.     margin: 50px 0;
9. }
11. .swagger-ui .info .title {
12.     color: #3b4151;
13.     font-family: sans-serif;
14.     font-size: 36px;
15. }
17. .swagger-ui .info .description {
18.     color: #3b4151;
19.     font-family: sans-serif;
20. }
22. .swagger-ui .opblock .opblock-summary-description {
23.     font-family: sans-serif;
24.     color: #3b4151;
25. }
26. `;
28. app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs, { customCss }));

复制代码

5.2 自定义Logo和标题

我们可以自定义Swagger UI的Logo和标题：

在Spring Boot中，我们可以创建一个自定义的HTML文件，并在其中添加Logo和标题：

2. <!-- src/main/resources/static/swagger-ui.html -->
3. <!DOCTYPE html>
4. <html>
5. <head>
6.     <meta charset="UTF-8">
7.     <title>My API Documentation</title>
8.     <link rel="stylesheet" type="text/css" href="./swagger-ui.css" />
9.     <link rel="stylesheet" type="text/css" href="./swagger.css" />
10.     <link rel="icon" type="image/png" href="./favicon-32x32.png" sizes="32x32" />
11.     <link rel="icon" type="image/png" href="./favicon-16x16.png" sizes="16x16" />
12.     <style>
13.         html
14.         {
15.             box-sizing: border-box;
16.             overflow: -moz-scrollbars-vertical;
17.             overflow-y: scroll;
18.         }
19.         *, *:before, *:after
20.         {
21.             box-sizing: inherit;
22.         }
23.         body {
24.             margin:0;
25.             background: #fafafa;
26.         }
27.     </style>
28. </head>
29. <body>
30.     <div id="swagger-ui"></div>
31.     <script src="./swagger-ui-bundle.js"></script>
32.     <script src="./swagger-ui-standalone-preset.js"></script>
33.     <script>
34.         window.onload = function() {
35.             const ui = SwaggerUIBundle({
36.                 url: "/v2/api-docs",
37.                 dom_id: '#swagger-ui',
38.                 deepLinking: true,
39.                 presets: [
40.                     SwaggerUIBundle.presets.apis,
41.                     SwaggerUIStandalonePreset
42.                 ],
43.                 plugins: [
44.                     SwaggerUIBundle.plugins.DownloadUrl
45.                 ],
46.                 layout: "StandaloneLayout",
47.                 validatorUrl: null,
48.                 customSiteTitle: "My API Documentation"
49.             });
50.         };
51.     </script>
52. </body>
53. </html>

复制代码

在Node.js中，我们可以使用自定义HTML模板：

2. const swaggerOptions = {
3.   customCss: '.swagger-ui .topbar { display: none }',
4.   customSiteTitle: "My API Documentation",
5.   customfavIcon: "/favicon.ico",
6.   customHtml: true
7. };
9. // Create a custom HTML template
10. app.get('/api-docs', (req, res) => {
11.   res.send(`
12.     <!DOCTYPE html>
13.     <html>
14.     <head>
15.         <meta charset="UTF-8">
16.         <title>My API Documentation</title>
17.         <link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist@3.25.0/swagger-ui.css" >
18.         <link rel="icon" type="image/png" href="/favicon.ico" sizes="32x32" />
19.         <style>
20.             html {
21.                 box-sizing: border-box;
22.                 overflow: -moz-scrollbars-vertical;
23.                 overflow-y: scroll;
24.             }
25.             *, *:before, *:after {
26.                 box-sizing: inherit;
27.             }
28.             body {
29.                 margin:0;
30.                 background: #fafafa;
31.             }
32.             .custom-logo {
33.                 max-width: 150px;
34.                 margin: 20px auto;
35.                 display: block;
36.             }
37.         </style>
38.     </head>
39.     <body>
40.         <img src="/logo.png" class="custom-logo" alt="Logo">
41.         <div id="swagger-ui"></div>
42.         <script src="https://unpkg.com/swagger-ui-dist@3.25.0/swagger-ui-bundle.js"></script>
43.         <script src="https://unpkg.com/swagger-ui-dist@3.25.0/swagger-ui-standalone-preset.js"></script>
44.         <script>
45.             window.onload = function() {
46.                 const ui = SwaggerUIBundle({
47.                     url: "/api-docs/swagger.json",
48.                     dom_id: '#swagger-ui',
49.                     deepLinking: true,
50.                     presets: [
51.                         SwaggerUIBundle.presets.apis,
52.                         SwaggerUIStandalonePreset
53.                     ],
54.                     plugins: [
55.                         SwaggerUIBundle.plugins.DownloadUrl
56.                     ],
57.                     layout: "StandaloneLayout"
58.                 });
59.             };
60.         </script>
61.     </body>
62.     </html>
63.   `);
64. });

复制代码

5.3 自定义JavaScript功能

我们还可以添加自定义JavaScript功能来扩展Swagger UI：

2. const swaggerOptions = {
3.   customJs: '/custom-swagger.js'
4. };
6. // Create custom JavaScript file
7. app.get('/custom-swagger.js', (req, res) => {
8.   res.send(`
9.     // Custom JavaScript for Swagger UI
10.     window.addEventListener('load', function() {
11.         console.log('Custom Swagger UI loaded');
12.         
13.         // Add custom button
14.         const customButton = document.createElement('button');
15.         customButton.innerText = 'Custom Action';
16.         customButton.className = 'btn';
17.         customButton.onclick = function() {
18.             alert('Custom action triggered!');
19.         };
20.         
21.         // Find the top bar and add the custom button
22.         const topbar = document.querySelector('.topbar');
23.         if (topbar) {
24.             topbar.appendChild(customButton);
25.         }
26.     });
27.   `);
28. });
30. app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs, swaggerOptions));

复制代码

6. 最佳实践

使用Swagger UI时，遵循一些最佳实践可以帮助我们创建更好的API文档。

6.1 文档编写最佳实践

为每个API端点提供清晰的描述，包括其用途、参数和返回值：

2. @ApiOperation(value = "Get user by ID", notes = "Retrieve a user by their unique identifier. Returns 404 if the user is not found.")
3. @ApiResponses({
4.     @ApiResponse(code = 200, message = "Successfully retrieved user", response = User.class),
5.     @ApiResponse(code = 404, message = "User not found")
6. })
7. @GetMapping("/{id}")
8. public ResponseEntity<User> getUserById(
9.     @ApiParam(value = "The unique identifier of the user", required = true, example = "1")
10.     @PathVariable Long id) {
11.     // ...
12. }

复制代码

为API请求和响应提供示例，使开发人员更容易理解如何使用API：

2. @ApiOperation(value = "Create a new user", notes = "Add a new user to the system")
3. @ApiResponses({
4.     @ApiResponse(code = 201, message = "User created successfully", response = User.class),
5.     @ApiResponse(code = 400, message = "Invalid input")
6. })
7. @PostMapping
8. public ResponseEntity<User> createUser(
9.     @ApiParam(
10.         value = "User object to be created",
11.         required = true,
12.         examples = @Example(value = {
13.             @ExampleProperty(
14.                 value = "{\n  "username": "johndoe",\n  "email": "john@example.com"\n}",
15.                 mediaType = "application/json"
16.             )
17.         })
18.     )
19.     @RequestBody User user) {
20.     // ...
21. }

复制代码

使用标记（tags）对API进行分类，使文档更有组织性：

2. @RestController
3. @RequestMapping("/api/users")
4. @Api(tags = {"User Management"})
5. public class UserController {
6.     // ...
7.    
8.     @GetMapping
9.     @ApiOperation(value = "Get all users", tags = {"User Management", "Admin"})
10.     public List<User> getAllUsers() {
11.         // ...
12.     }
13.    
14.     @PostMapping
15.     @ApiOperation(value = "Create a new user", tags = {"User Management"})
16.     public User createUser(@RequestBody User user) {
17.         // ...
18.     }
19. }

复制代码

6.2 安全性最佳实践

在生产环境中，应该限制对Swagger UI的访问：

2. @Configuration
3. @Profile("!prod") // Only enable Swagger in non-production environments
4. @EnableSwagger2
5. public class SwaggerConfig {
6.     // ...
7. }

复制代码

或者使用Spring Security来限制访问：

2. @Configuration
3. @EnableWebSecurity
4. public class SecurityConfig extends WebSecurityConfigurerAdapter {
6.     @Override
7.     protected void configure(HttpSecurity http) throws Exception {
8.         http
9.             .authorizeRequests()
10.                 .antMatchers("/v2/api-docs", "/swagger-resources/**", "/swagger-ui.html", "/webjars/**").hasRole("DEVELOPER")
11.                 .anyRequest().authenticated()
12.             .and()
13.             .formLogin()
14.             .and()
15.             .httpBasic();
16.     }
17. }

复制代码

避免在API文档中暴露敏感信息，如密码、密钥等：

2. public class User {
3.     @ApiModelProperty(notes = "The user's username", required = true)
4.     private String username;
5.    
6.     @ApiModelProperty(notes = "The user's email address", required = true)
7.     private String email;
8.    
9.     @ApiModelProperty(hidden = true) // Hide password field from documentation
10.     private String password;
11.    
12.     // ...
13. }

复制代码

6.3 版本控制最佳实践

使用版本控制来管理API的变化：

2. @RestController
3. @RequestMapping("/api/v1/users")
4. @Api(tags = {"User Management v1"})
5. public class UserControllerV1 {
6.     // ...
7. }
9. @RestController
10. @RequestMapping("/api/v2/users")
11. @Api(tags = {"User Management v2"})
12. public class UserControllerV2 {
13.     // ...
14. }

复制代码

为不同版本的API提供不同的文档：

2. @Bean
3. public Docket apiV1() {
4.     return new Docket(DocumentationType.SWAGGER_2)
5.             .groupName("v1")
6.             .select()
7.             .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller.v1"))
8.             .paths(PathSelectors.ant("/api/v1/**"))
9.             .build()
10.             .apiInfo(apiV1Info());
11. }
13. @Bean
14. public Docket apiV2() {
15.     return new Docket(DocumentationType.SWAGGER_2)
16.             .groupName("v2")
17.             .select()
18.             .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller.v2"))
19.             .paths(PathSelectors.ant("/api/v2/**"))
20.             .build()
21.             .apiInfo(apiV2Info());
22. }

复制代码

7. 常见问题与解决方案

在使用Swagger UI时，可能会遇到一些常见问题。下面是一些解决方案。

7.1 Swagger UI无法加载

解决方案：

1. 检查依赖是否正确配置
2. 确认Spring Boot应用程序是否正常运行
3. 检查浏览器控制台是否有错误信息
4. 尝试清除浏览器缓存

对于Spring Boot项目，确保以下依赖已正确添加：

2. <dependency>
3.     <groupId>io.springfox</groupId>
4.     <artifactId>springfox-swagger2</artifactId>
5.     <version>3.0.0</version>
6. </dependency>
7. <dependency>
8.     <groupId>io.springfox</groupId>
9.     <artifactId>springfox-swagger-ui</artifactId>
10.     <version>3.0.0</version>
11. </dependency>

复制代码

解决方案：

1. 确保控制器类上有@RestController或@Controller注解
2. 检查@EnableSwagger2注解是否已添加到主应用程序类
3. 确认控制器包路径是否在Docket配置中正确指定

2. @Configuration
3. @EnableSwagger2
4. public class SwaggerConfig {
5.     @Bean
6.     public Docket api() {
7.         return new Docket(DocumentationType.SWAGGER_2)
8.                 .select()
9.                 .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
10.                 .paths(PathSelectors.any())
11.                 .build();
12.     }
13. }

复制代码

7.2 注解不生效

解决方案：

1. 确保已导入正确的注解包：import io.swagger.annotations.*;
2. 检查注解语法是否正确
3. 确认Spring Boot应用程序是否已重新启动

2. import io.swagger.annotations.Api;
3. import io.swagger.annotations.ApiOperation;
4. import io.swagger.annotations.ApiParam;
5. import io.swagger.annotations.ApiResponse;
6. import io.swagger.annotations.ApiResponses;
8. @RestController
9. @RequestMapping("/api/users")
10. @Api(tags = "User Management API")
11. public class UserController {
12.    
13.     @GetMapping("/{id}")
14.     @ApiOperation(value = "Get user by ID", notes = "Retrieve a user by their ID")
15.     @ApiResponses({
16.         @ApiResponse(code = 200, message = "Successfully retrieved user"),
17.         @ApiResponse(code = 404, message = "User not found")
18.     })
19.     public User getUserById(
20.             @ApiParam(value = "User ID", required = true) @PathVariable Long id) {
21.         // ...
22.     }
23. }

复制代码

7.3 认证问题

解决方案：

1. 配置安全方案
2. 在API上添加安全注解

2. @Configuration
3. @EnableSwagger2
4. public class SwaggerConfig {
5.    
6.     @Bean
7.     public Docket api() {
8.         return new Docket(DocumentationType.SWAGGER_2)
9.                 .select()
10.                 .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
11.                 .paths(PathSelectors.any())
12.                 .build()
13.                 .securitySchemes(Arrays.asList(apiKey()))
14.                 .securityContexts(Arrays.asList(securityContext()));
15.     }
16.    
17.     private ApiKey apiKey() {
18.         return new ApiKey("JWT", "Authorization", "header");
19.     }
20.    
21.     private SecurityContext securityContext() {
22.         return SecurityContext.builder()
23.                 .securityReferences(defaultAuth())
24.                 .forPaths(PathSelectors.regex("/api/.*"))
25.                 .build();
26.     }
27.    
28.     private List<SecurityReference> defaultAuth() {
29.         AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
30.         AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
31.         authorizationScopes[0] = authorizationScope;
32.         return Arrays.asList(new SecurityReference("JWT", authorizationScopes));
33.     }
34. }

复制代码

在控制器中添加安全注解：

2. @GetMapping("/secure")
3. @ApiOperation(value = "Secure endpoint", notes = "This endpoint requires authentication")
4. @ApiResponses({
5.     @ApiResponse(code = 200, message = "Successfully accessed secure endpoint"),
6.     @ApiResponse(code = 401, message = "Unauthorized")
7. })
8. @SecurityRequirement(name = "JWT")
9. public String secureEndpoint() {
10.     return "Access granted to secure endpoint";
11. }

复制代码

7.4 性能问题

解决方案：

1. 限制API文档的范围
2. 禁用不必要的模型
3. 使用缓存

2. @Bean
3. public Docket api() {
4.     return new Docket(DocumentationType.SWAGGER_2)
5.             .select()
6.             .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
7.             .paths(PathSelectors.any())
8.             .build()
9.             .apiInfo(apiInfo())
10.             .produces(Collections.singleton("application/json"))
11.             .consumes(Collections.singleton("application/json"))
12.             .ignoredParameterTypes(ExampleIgnoreClass.class); // Ignore certain model classes
13. }

复制代码

解决方案：

1. 在开发环境启用Swagger，在生产环境禁用
2. 使用懒加载

2. @Configuration
3. @Profile("dev") // Only enable Swagger in development environment
4. @EnableSwagger2
5. public class SwaggerConfig {
6.     // ...
7. }

复制代码

或者使用条件加载：

2. @Bean
3. @ConditionalOnProperty(name = "swagger.enabled", havingValue = "true")
4. public Docket api() {
5.     return new Docket(DocumentationType.SWAGGER_2)
6.             // ...
7. }

复制代码

在application.properties中：

2. # Enable Swagger in development
3. swagger.enabled=true

复制代码

8. 总结

Swagger UI是一个强大的工具，可以帮助我们创建专业、交互式的API文档。通过本文的介绍，我们了解了如何从环境准备到项目集成，再到优化配置，全面搭建Swagger UI界面。

我们首先介绍了Swagger UI的基本概念和重要性，然后详细讲解了如何在Spring Boot和Node.js项目中集成Swagger UI，包括添加依赖、创建配置类、编写控制器和模型等步骤。接着，我们探讨了Swagger UI的基本配置和高级配置，包括API信息配置、分组配置、自定义模型属性等。我们还介绍了如何自定义Swagger UI的界面，包括自定义CSS、Logo和标题，以及添加自定义JavaScript功能。最后，我们分享了一些使用Swagger UI的最佳实践和常见问题的解决方案。

通过正确地使用Swagger UI，我们可以大大提高API文档的质量和可用性，使开发人员能够更容易地理解和使用我们的API。希望本文能够帮助您构建一个专业的API文档平台，提升您的API开发和文档编写体验。