Ubuntu下Swagger集成有哪些步骤

Ubuntu下Swagger集成的常见步骤（以Node.js/Express和Spring Boot为例）

一、通用前置准备

在Ubuntu上集成Swagger前，需确保系统具备Node.js/npm（用于前端工具链）和Java（部分Java项目依赖）环境：

1. 安装Node.js和npm（适用于Node.js/Express项目）：

   sudo apt update sudo apt install -y nodejs npm 

   验证安装：node -v（显示版本号）、npm -v（显示版本号）。

2. 安装Java（适用于Spring Boot项目）：

   sudo apt update sudo apt install -y openjdk-11-jdk 

   验证安装：java -version（显示Java版本信息）。

二、Node.js/Express项目集成Swagger

若项目基于Node.js+Express框架，可通过swagger-jsdoc（生成文档）和swagger-ui-express（集成UI）快速实现：

1. 安装Swagger工具（全局或项目本地）：

   sudo npm install -g swagger-jsdoc swagger-ui-express # 全局安装（可选） cd your-project-directory npm install --save swagger-jsdoc swagger-ui-express # 项目本地安装（推荐） 

2. 创建Swagger配置文件：
   在项目根目录新建swagger.yaml（或swagger.json），定义API基本信息、路径、模型等。示例如下：

   swagger: '2.0' info: title: Sample API description: A demo API for Swagger integration version: '1.0.0' host: localhost:3000 basePath: /api schemes: - http paths: /users: get: summary: Get all users responses: '200': description: A list of users schema: type: array items: $ref: '#/definitions/User' definitions: User: type: object properties: id: type: integer format: int64 name: type: string 

3. 集成Swagger UI到Express应用：
   修改Express主文件（如app.js），添加以下代码：

   const express = require('express'); const swaggerUi = require('swagger-ui-express'); const swaggerDocument = require('./swagger.yaml'); // 引入配置文件 const app = express(); app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument)); // 挂载Swagger UI // 其他路由（如用户接口） app.get('/api/users', (req, res) => { res.json([{ id: 1, name: 'John' }, { id: 2, name: 'Jane' }]); }); const PORT = process.env.PORT || 3000; app.listen(PORT, () => console.log(`Server running on port ${PORT}`)); 

4. 运行并访问Swagger UI：

   node app.js 

   打开浏览器访问http://localhost:3000/api-docs，即可看到Swagger UI界面，包含API文档和测试功能。

三、Spring Boot项目集成Swagger

若项目基于Spring Boot框架，可通过Springfox Swagger依赖自动生成文档：

1. 添加Swagger依赖：
   在pom.xml（Maven）中添加以下依赖：

   <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency> 

2. 配置Swagger：
   创建配置类（如SwaggerConfig.java），启用Swagger并定义扫描范围：

   import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) // 替换为你的控制器包路径 .paths(PathSelectors.any()) .build(); } } 

3. 运行并访问Swagger UI：
   使用Maven启动Spring Boot应用：

   ./mvnw spring-boot:run 

   打开浏览器访问http://localhost:8080/swagger-ui.html，即可查看自动生成的API文档。

四、可选：Docker集成Swagger UI

若不想手动安装，可使用Docker快速部署Swagger UI：

1. 安装Docker：

   sudo apt update sudo apt install -y docker.io sudo systemctl start docker sudo systemctl enable docker 

2. 运行Swagger UI容器：

   docker pull swaggerapi/swagger-ui docker run -d -p 8080:8080 --name swagger-ui swaggerapi/swagger-ui 

   访问http://localhost:8080，通过界面输入Swagger规范文件URL（如http://your-server-ip:3000/api-docs）即可查看文档。

以上步骤覆盖了Ubuntu下Swagger集成的常见场景，可根据项目技术栈选择对应方案。集成后，可通过Swagger UI直观查看API文档、测试接口，提升开发效率。