如何使用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文档，提升团队协作效率。

声明：本文内容由网友自发贡献，本站不承担相应法律责任。对本内容有异议或投诉，请联系2913721942#qq.com核实处理，我们将尽快回复您，谢谢合作！