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

CentOS环境下生成Swagger API文档的完整流程（以Spring Boot项目为例）

1. 环境准备

在CentOS系统上，首先需要安装Java和Maven（Swagger依赖Java环境，Maven用于项目构建）。

安装Java：
执行sudo yum install -y java-1.8.0-openjdk-devel安装OpenJDK 8，安装完成后通过java -version验证是否成功。
安装Maven：
执行sudo yum install -y maven安装Maven，安装完成后通过mvn -version验证是否成功。

2. Spring Boot项目集成Swagger

若项目为Spring Boot应用，需通过Maven添加Swagger核心依赖，实现自动生成API文档。

添加依赖：
在项目的pom.xml文件中添加以下依赖（版本可根据需求调整）：

<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），使用@EnableSwagger2注解启用Swagger，并通过Docket Bean配置文档规则：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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)
                .apiInfo(new ApiInfoBuilder()
                        .title("API文档标题")
                        .description("API文档详细描述")
                        .version("1.0.0")
                        .build())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) // 指定扫描的控制器包路径
                .paths(PathSelectors.any()) // 扫描所有路径
                .build();
    }
}

上述配置中，RequestHandlerSelectors.basePackage用于指定Swagger扫描的控制器包，PathSelectors.any()表示扫描所有API路径。

3. 编写API注解（增强文档可读性）

通过Swagger提供的注解，可详细描述API的功能、参数、返回值等信息，使生成的文档更易理解。

类级别注解：在控制器类上使用@Api注解，标注该控制器的功能模块（如“用户管理”）：

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

@RestController
@RequestMapping("/users")
@Api(tags = "用户管理") // 描述该控制器的功能
public class UserController {
    // ...
}

方法级别注解：在API方法上使用@ApiOperation注解，描述API的具体功能（如“获取所有用户”）：

import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import java.util.List;

@GetMapping
@ApiOperation(value = "获取所有用户", notes = "返回系统中所有用户的列表") // 描述API功能
public List<User> getAllUsers() {
    // ...
}

参数注解：在方法参数上使用@ApiParam注解，描述参数的含义（如“用户ID”）：

import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;

@GetMapping("/{id}")
@ApiOperation(value = "根据ID获取用户", notes = "根据用户ID查询单个用户信息")
public User getUserById(
    @ApiParam(value = "用户ID", required = true) @PathVariable Long id // 描述参数含义及是否必填
) {
    // ...
}

模型注解：在实体类上使用@ApiModel和@ApiModelProperty注解，描述模型及其属性（如“用户实体”）：

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(description = "用户实体类，用于描述用户信息")
public class User {
    @ApiModelProperty(value = "用户ID", example = "1")
    private Long id;
    
    @ApiModelProperty(value = "用户名", example = "张三")
    private String name;
    
    @ApiModelProperty(value = "用户邮箱", example = "zhangsan@example.com")
    private String email;
    
    // getters and setters
}

这些注解会自动生成到API文档中，帮助开发者快速理解API的使用方式。

4. 启动项目并访问Swagger UI

完成上述配置后，启动Spring Boot项目（通过mvn spring-boot:run或IDE启动）。启动成功后，在浏览器中访问以下URL即可查看Swagger UI界面：

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

（注：若项目端口不是8080，需替换为实际端口，如http://localhost:8081/swagger-ui.html）。
访问后，可看到所有扫描到的API接口列表，点击接口名称可查看详细信息（包括请求参数、返回值、示例等），并支持在线测试API。

5. 可选：生成静态API文档

若需要将API文档导出为静态文件（如HTML、JSON），可使用Swagger Maven插件。

添加插件配置：在pom.xml文件的<build>标签中添加以下插件：

<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-sources/swagger</outputDirectory> <!-- 生成目录 -->
                        <configurationFile>${project.basedir}/src/main/resources/swagger.yaml</configurationFile> <!-- 配置文件路径 -->
                        <sourceDirectory>${project.basedir}/src/main/java</sourceDirectory> <!-- 源代码目录 -->
                        <language>java</language> <!-- 语言类型 -->
                        <generateApis>true</generateApis> <!-- 生成API文档 -->
                        <generateModels>true</generateModels> <!-- 生成模型文档 -->
                        <generateSupportingFiles>true</generateSupportingFiles> <!-- 生成支持文件 -->
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

生成文档：执行mvn clean package命令，插件会将API文档生成到指定的outputDirectory目录下（如target/generated-sources/swagger），生成的文档格式包括JSON、YAML等。

通过以上步骤，即可在CentOS环境下为Spring Boot项目生成并管理Swagger API文档，实现API文档的自动生成与可视化展示。

0 赞

0 踩