Ubuntu下Swagger集成有哪些步骤 - 问答

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

一、通用前置准备

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

安装Node.js和npm（适用于Node.js/Express项目）：
```
sudo apt update
sudo apt install -y nodejs npm
```
验证安装：node -v（显示版本号）、npm -v（显示版本号）。
安装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）快速实现：

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

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

创建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

集成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}`));

运行并访问Swagger UI：
```
node app.js
```
打开浏览器访问http://localhost:3000/api-docs，即可看到Swagger UI界面，包含API文档和测试功能。

三、Spring Boot项目集成Swagger

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

添加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>

配置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();
    }
}

运行并访问Swagger UI：
使用Maven启动Spring Boot应用：
```
./mvnw spring-boot:run
```
打开浏览器访问http://localhost:8080/swagger-ui.html，即可查看自动生成的API文档。

四、可选：Docker集成Swagger UI

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

安装Docker：

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

运行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文档、测试接口，提升开发效率。

0 赞

0 踩