SpringBoot-25-SpringBoot整合Swagger2以及Swagger-Bootstrap-Ui的使用
我们在之前的文章中讲过了RESTful风格设计API，没有看过的小伙伴可以查找之前的文章看一下，那么在针对这些API我们需要怎么进行测试呢？也许你会说你通过单元测试、postman、IDEA的http client
等等方式吧。但是当我们要和前端开发进行交互的时候我们不仅仅需要自己测试通过，同时还需要给前端工程师这个API接口的开发文档，以及每次测试修改接口后，要对文档进行维护，这就增加了我们
程序开发的成本，并且经常文档维护维护就中断了，那么它就失去了参考价值，变得没有意义。Swagger的出现就是为了解决这些痛点的。个人认为Swagger有以下优点：
Swagger提供了API接口文档，并且将代码维护和文档修改融为一体，减少创建文档的麻烦
Swagger提供了前端界面用来测试每一个API接口
跨语言，支持多国语言
那么现在我们开始进行Swagger的代码之旅吧
引入Swagger的依赖
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
创建Swagger配置类
创建一个swagger的config配置代码如下：
@Configuration @EnableSwagger2 public class Swagger2Config { @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .enable(true) .apiInfo(apiInfo()) .select() // 扫描需要生成API文档的controller所在的包路径 .apis(RequestHandlerSelectors.basePackage("com.learn.springboot.controller")) //为有@Api注解的Controller生成API文档 // .apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) //为有@ApiOperation注解的方法生成API文档 // .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Spring Boot 2.x集成Swagger") .description("测试 API 1.0 操作文档") .termsOfServiceUrl("test") .version("1.0") .contact(new Contact("springboot葵花宝典", "", "test@gmail.com")) .build(); } }
注
- @Configuration：声明Swagger2Config为配置类
- @EnableSwagger2：声明配置Swagger配置
配置Swagger的测试API
经过上面的操作后，Swagger页面以及可以看到基本信息了，但是我们还没有添加相关的API信息，现在我们就添加相关的API操作，代码如下：
Student实体类
@Data @ApiModel(value = "学生实体类",description = "学生信息用作增删改查") @JsonPropertyOrder(value={"name","mobile","sex"}) public class Student implements Serializable{ @ApiModelProperty(value = "学生ID", name = "id", required = false, example = "0") @JsonIgnore private Long id; @ApiModelProperty(value = "学生电话", name = "mobile", required = true,example = "133333") private String mobile; @ApiModelProperty(value = "学生性别", name = "性别", required = true,example = "男") @JsonProperty("性别") private String sex; @ApiModelProperty(value = "学生姓名", name = "name", required = true,example = "张三") private String name; @ApiModelProperty(value = "学生年龄", name = "age", required = true,example = "20") private int age; @ApiModelProperty(value = "邮箱", name = "email", required = true,example = "133@qq.com") @JsonProperty("邮箱") private String email; @ApiModelProperty(value = "是否可用1可用，0不不用", name = "isEnabled", required = false,example = "1") private int isEnabled; @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8") private Date createDate; private Date updateDate; }
注解：
- ApiModel：作用在实体类上，表示响应数据
- @ApiModelProperty：实体类属性的描述
添加Controller
@Api(value = "测试Swagger",tags = "测试") @RestController @RequestMapping("/test") public class TestController { /** *测试 */ @ApiImplicitParams({ @ApiImplicitParam(name = "name", value = "name", required = false, paramType = "path",dataType = "String", example = "张三"), }) @ApiOperation(value = "测试",tags = "测试",notes = "测试swagger") @GetMapping("/{name}") public String test(@PathVariable("name")String name) { return "Hello :" +name; } /** *测试student */ @ApiOperation(value = "测试student",tags = "测试student",notes = "测试student") @PostMapping("/student") public Student testStudent(@RequestBody Student student) { return student; } }
注解：
- @Api:作用在Controller类上，value的值默认不显示，tag属性为具体描述
- @ApiOperation：作用在Controller类的方法上
- @ApiImplicitParams：方法中参数的说明
value:参数的说明
paramType：参数输出的位置，header(请求参数的获取：@RequestHeader)、query(请求参数的获取：@RequestParam)、path(请求参数的获取：@PathVariable)
dataType：参数类型
example:参数示例
required：参数是否必须
测试
启动项目，然后输入：
http://localhost:8080/swagger-ui.html进行测试。其整体展示效果如下：
使用Swagger进行测试
我们对测试方法接口将那些测试，点击Try it out
进入参数页面
输入name,点击execute,就完成了接口的请求了。
整合swagger-bootstrap-ui
swagger默认的api接口是上下结构，在浏览器中显示不符合我们开发系统的左右菜单风格，swagger-bootstrap-ui就是一套基于左右菜单风格，只需要在pom.xml中添加依赖即可。
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> <exclusions> <exclusion> <groupId>io.swagger</groupId> <artifactId>swagger-annotations</artifactId> </exclusion> <exclusion> <groupId>io.swagger</groupId> <artifactId>swagger-models</artifactId> </exclusion> </exclusions> </dependency> <!-- https://mvnrepository.com/artifact/com.github.xiaoymin/swagger-bootstrap-ui --> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>1.9.6</version> </dependency> <dependency> <groupId>io.swagger</groupId> <artifactId>swagger-annotations</artifactId> <version>1.5.21</version> </dependency> <dependency> <groupId>io.swagger</groupId> <artifactId>swagger-models</artifactId> <version>1.5.21</version> </dependency>
修改过依赖以后访问Swagger API文档
访问swagger-bootstrap-ui文档
- swagger文档地址：http://localhost:8080/doc.html
- swagger效果展示
实体类展示
方法展示
