如何使用CentOS Swagger生成API文档 - 问答

在CentOS上使用Swagger生成API文档的完整流程

一、环境准备

在开始前，需确保CentOS系统已更新并安装必要工具：

sudo yum update -y

1. 安装Java环境（适用于Java/Spring Boot项目）

Swagger依赖Java运行，需安装OpenJDK 8：

sudo yum install -y java-1.8.0-openjdk-devel
java -version  # 验证安装（需显示Java版本信息）

2. 安装Maven（用于Java项目构建）

Maven管理项目依赖及构建流程：

sudo yum install -y maven
mvn -version  # 验证安装（需显示Maven版本信息）

3. 安装Node.js和npm（适用于Node.js项目）

若使用Node.js编写API，需安装Node.js和包管理工具npm：

curl -sL https://rpm.nodesource.com/setup_14.x | sudo bash -
sudo yum install -y nodejs
node -v  # 验证Node.js版本
npm -v   # 验证npm版本

4. 安装Docker（可选，快速部署Swagger UI）

通过Docker可快速启动Swagger UI，无需手动配置：

sudo yum install -y docker
sudo systemctl start docker
sudo systemctl enable docker

二、针对不同技术栈的具体步骤

场景1：Java/Spring Boot项目（常用）

1. 添加Swagger依赖

在项目的pom.xml（Maven）中添加Swagger核心依赖：

<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扫描路径

创建Swagger配置类（如SwaggerConfig.java），指定API扫描的包路径：

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.controller")) // 替换为你的Controller包路径
                .paths(PathSelectors.any())
                .build();
    }
}

3. 添加API注释

在Controller类和方法上使用Swagger注解，描述API功能：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Api(tags = "用户管理API")  // 描述API模块
public class UserController {
    @GetMapping("/users")
    @ApiOperation("获取用户列表")  // 描述接口功能
    public String getUsers() {
        return "用户列表数据";
    }
}

4. 启动项目并访问Swagger UI

运行Spring Boot项目（mvn spring-boot:run），访问以下URL查看文档：

http://<服务器IP>:8080/swagger-ui.html

场景2：Node.js项目

1. 初始化Node.js项目

创建项目目录并初始化package.json：

mkdir my-node-api && cd my-node-api
npm init -y

2. 安装Swagger相关包

安装Express框架和Swagger UI中间件：

npm install express swagger-ui-express swagger-jsdoc

3. 配置Swagger文档

创建swagger.json（或swagger.yaml）文件，定义API基本信息和路径：

{
  "openapi": "3.0.0",
  "info": {
    "title": "Node.js API文档",
    "version": "1.0.0",
    "description": "这是一个Node.js示例API"
  },
  "servers": [
    {
      "url": "http://localhost:3000",
      "description": "本地开发服务器"
    }
  ],
  "paths": {
    "/hello": {
      "get": {
        "summary": "获取问候信息",
        "responses": {
          "200": {
            "description": "成功返回问候语",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

4. 集成Swagger到Express应用

创建app.js文件，将Swagger文档挂载到/api-docs路径：

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

const app = express();
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

// 示例API路由
app.get('/hello', (req, res) => {
    res.json({ message: "Hello, World!" });
});

app.listen(3000, () => {
    console.log('Server running at http://localhost:3000');
});

5. 启动应用并访问文档

运行Node.js应用（node app.js），访问以下URL查看文档：

http://<服务器IP>:3000/api-docs

场景3：使用Docker快速部署Swagger UI

若不想手动配置，可使用Docker快速启动Swagger UI：

docker pull swaggerapi/swagger-ui
docker run -p 80:80 -d swaggerapi/swagger-ui

访问http://<服务器IP>即可查看Swagger UI，默认会尝试加载远程API文档（如petstore.swagger.io）。若需指向本地文档，可通过-e参数设置SWAGGER_FILE环境变量，或修改容器内的index.html文件。

三、自动化生成文档（可选）

1. Java项目：使用Swagger Maven插件

在pom.xml中添加插件，生成静态文档：

<build>
    <plugins>
        <plugin>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-maven-plugin</artifactId>
            <version>2.1.9</version>
            <executions>
                <execution>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                    <configuration>
                        <outputDirectory>${project.build.directory}/generated-docs</outputDirectory>
                        <inputDirectory>${project.basedir}/src/main/java</inputDirectory>
                        <language>java</language>
                        <generateApis>true</generateApis>
                        <generateModels>true</generateModels>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

运行mvn clean package，生成的文档将存放在target/generated-docs目录。

2. Node.js项目：使用Swagger CLI

安装swagger-jsdoc命令行工具：

npm install -g swagger-jsdoc

通过命令生成文档：

swagger-jsdoc -i ./swagger-defs/*.js -o ./swagger.json

其中-i指定输入文件（如包含Swagger注释的JS文件），-o指定输出文件。

注意事项

安全性：生产环境中建议启用HTTPS，避免API文档泄露敏感信息。
版本兼容：确保Swagger依赖版本与项目技术栈兼容（如Spring Boot 2.x对应Swagger 2，Spring Boot 3.x对应Swagger 3/OpenAPI 3）。
文档维护：定期更新Swagger配置和注释，确保文档与API实际行为一致。

通过以上步骤，可在CentOS系统上快速生成并管理API文档，提升团队协作效率。

0 赞

0 踩