SpringBoot集成Swagger2生成接口文档的方法示例

下面是关于Spring Boot集成Swagger2生成接口文档的方法示例：

一、前置知识

• SpringBoot：JavaEE框架，用于构建基于Java的web应用程序。
• Swagger：用于API文档的工具。

二、创建Spring Boot应用

在创建Spring Boot应用之前，需要安装好Java和Maven。使用Spring Initializr快速创建一个简单的Spring Boot应用。可以在 Spring Initializr 网站上创建,也可在IDE中使用该向导来创建。

三、添加Swagger2依赖

在 Maven 项目中添加以下依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger.version}</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger.version}</version>
</dependency>

其中 ${swagger.version} 为当前使用的版本。

四、Swagger2配置

创建Swagger2配置类 Swagger2Config ，使用 @Configuration 标注它，并在其中添加 @EnableSwagger2 注解启用 Swagger2。

示例1：配置Swagger2Config类

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("更多请关注我的博客：https://www.xyd666.com/")
                .termsOfServiceUrl("https://www.xyd666.com/")
                .contact("xyd666")
                .version("1.0")
                .build();
    }
}

其中：

• createRestApi 方法创建并返回一个 Docket 对象，用于指定扫描的包和API文档的属性。
• apiInfo 方法返回一个 ApiInfo 对象，其中包含了API文档的标题、描述、联系方式等信息。

示例2：基于注解方式显示API文档

@RestController
@RequestMapping("/user")
@Api(value = "user-api", tags = {"用户操作相关接口"})
public class UserController {
    @ApiOperation(value = "获取用户列表", notes = "获取全部用户列表", httpMethod = "GET")
    @GetMapping("/list")
    public List<User> getUserList() {
        // ... codes to get user list ...
        return userList;
    }
}

其中每个注解的作用如下：

• @RestController: 标记这个类为Spring MVC 的Controller。
• @RequestMapping("/user"): 定义请求的URL路径。
• @Api(value = "user-api", tags = {"用户操作相关接口"}): 将java类标记为Swagger资源，比如一个 Controller。
• @ApiOperation: 描述HTTP接口的基本信息，可以用于生成API文档。其中value 为接口名称，notes 为接口描述，httpMethod 为接口的HTTP方法。

一、结束语

以上就是Spring Boot集成Swagger2生成接口文档的方法示例。通过本文中的方法，可以快速地生成API文档，方便开发者进行开发和测试。