CentOS Swagger API文档如何生成
导读：CentOS环境下生成Swagger API文档的完整流程（以Spring Boot项目为例） 1. 环境准备 在CentOS系统上，首先需要安装Java和Maven（Swagger依赖Java环境，Maven用于项目构建）。 安装Jav...
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，并通过DocketBean配置文档规则：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 }
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文档的自动生成与可视化展示。
声明：本文内容由网友自发贡献，本站不承担相应法律责任。对本内容有异议或投诉，请联系2913721942#qq.com核实处理，我们将尽快回复您，谢谢合作！
若转载请注明出处： CentOS Swagger API文档如何生成
本文地址： https://pptw.com/jishu/727411.html