SpringBoot集成Swagger2构建在线接口文档

导读

　　自从软件架构从单一模式“拥抱”微服务依赖，项目的结构演变逐步走向前后端分离的模式，而且前后端的技术栈越来越清晰，职责越加明确。从而导致前后端更加的松耦合，合作的纽带只剩下接口。

　　因此接口变的更加重要，随着项目更新迭代，接口量越来越多，从而导致接口文档维护愈发困难。开发人员在开发新接口时，不得不兼顾更新旧接口文档，导致开发人员的工作愈发繁重。再这样的“历史背景”下，Swagger“横空出世”，旨在解救劳苦大众。

　　Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

　　总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单，可以利用 Swagger 在线接口文档测试接口数据，这给开发人员提供了便利。

项目POM

<parent>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-parent</artifactId>
	<version>2.5.2</version>
	<relativePath/> <!-- lookup parent from repository -->
</parent>
<dependencies>
	<dependency>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-web</artifactId>
	</dependency>

	<dependency>
		<groupId>org.projectlombok</groupId>
		<artifactId>lombok</artifactId>
		<optional>true</optional>
	</dependency>
	<dependency>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-test</artifactId>
		<scope>test</scope>
	</dependency>
<!--        swagger2-->
	<dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger2</artifactId>
		<version>2.6.1</version>
	</dependency>
<!--        swagger-ui-->
	<dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger-ui</artifactId>
		<version>2.6.1</version>
	</dependency>


</dependencies>

Controller

@RestController
@RequestMapping("user")
@Slf4j
// 注意：tags不要写中文，否则点击swagger-ui.html页面中的接口链接可能无反应
@Api(tags = {"user REST Api"})
public class UserController {

    @GetMapping("simple/{id}/")
    @ApiOperation("查询单个user")
    public User simple(@PathVariable("id") @ApiParam(name = "id", value = "user主键") Integer id) {
        log.info(">>>>>>>>>>>>>> simple start... id = {}", id);
        return new User("张三", null);
    }
}

// 入参和返回值 只作为演示。

SwaggerConfig配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()).select()
                // 这里basePackage 指的是 将哪个包作为api接口进行扫描
                .apis(RequestHandlerSelectors.basePackage("com.xxxx.controller"))
                .paths(PathSelectors.any()).build();
    }

    public ApiInfo apiInfo(){
                // Swagger接口文档的标题，描述，联系人等信息
        return new ApiInfoBuilder().title("Swagger接口文档")
                .description("这是Swagger接口文档描述")
                .contact("作者:66KG").version("V1.0").build();
    }
}

user实体类

@Data
@NoArgsConstructor
@AllArgsConstructor
@Accessors(chain = true)
@ApiModel("user实体类")
public class User implements Serializable {

    @ApiModelProperty(name = "name", value = "姓名")
    private String name;

    @ApiModelProperty(name = "password", value = "密码")
    private String password;


}

启动项目

@SpringBootApplication
public class SpringbootDemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(SpringbootDemoApplication.class, args);
    }

}

查看Swagger接口效果

打开浏览器，输入localhost:8080/swagger-ui.html

Swagger常用注解

@Api(tags = {"user REST Api"})	一般用于Controller类上，表示该类是关于xx的接口API

@ApiOperation("查询单个user")	用于Controller类的具体接口方法上，表示具体接口含义

@ApiParam(name = "id", value = "user主键") Integer id	用于方法入参

@ApiModel("user实体类")	用于实体类

@ApiModelProperty(name = "name", value = "姓名")	用于实体类的成员属性

  测试接口

总结

　　至此，本文详细讲解了Swagger是什么，以及 Spring Boot 整合 Swagger2的步骤，包括配置，相关注解的讲解，涉及到了实体类和接口类，以及如何使用。希望小伙伴们马上用起来吧。