测试API框架 - Swagger介绍及Springboot集成

痛点

前后端编写接口文档的痛苦编写及维护接口文档耗费不少精力，来不及更新接口文档描述不正确

Swagger的作用

Swagger：https://swagger.io/ 在前后台分离的开发模式中，减小接口定义沟通成本，方便开发过程中测试，自动生成接口文档

Springboot集成Swagger

maven依赖：pom.xml

作为Java服务端的大一统框架Spring，将Swagger规范纳入自身的标准，建立了Spring-swagger项目，后面改成了现在的Springfox

<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无法运行 package demo.config; import io.swagger.annotations.Api; 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.service.ApiInfo; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; /* * Author : zfk * Date : 14:46 */ @Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket createRestApi(){ return new Docket(DocumentationType.SWAGGER_2) // 指定api类型为swagger2 .apiInfo(apiInfo()) // 用于定义api文档汇总信息,即下面的配置 .select() .apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) // 指定controller类,即加了Api注解的类 .paths(PathSelectors.any()) // 选择所有controller .build(); } //构建api文档的相关信息 private ApiInfo apiInfo(){ return new ApiInfoBuilder() // 页面标题 .title("JPATest API Doc") // 描述 .description("This is a restful api document of nc server.") //版本号 .version("1.0") .build(); } }

Docket是核心类，这里用流式编程，还有很多属性

其中.apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) 中指定controller为加了Api注解的类，其实RequestHandlerSelectors还有其他的配置

扫描包.apis(RequestHandlerSelectors.basePackage("com.demo.controller"))

Controller配置

首先我们在Docket配置Controller是所有加上了@Api注解的类（也可以设置为扫描包） 接口上需要设置@ApiOperation注解

一个UserController：因为这里是讲Swagger，就不贴Springboot的mvc代码

package demo.controller; import demo.entity.User; import demo.service.UserService; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.PathVariable; import org.springframework.web.bind.annotation.RestController; import java.util.Optional; /** * Author : zfk * Date : 14:40 */ @RestController @Api("UserController") public class UserController { @Autowired private UserService service; @GetMapping("/findById/{id}") @ApiOperation(value = "findById") public User findById(@PathVariable("id") String id){ Optional<User> user = service.findById(id); return user.get(); } @GetMapping("/finByName/{name}") @ApiOperation(value = "findByName") public User findByName(@PathVariable("name")String name){ User user = service.findByName(name); return user; } } 运行Springboot后，访问地址http://localhost:8080/swagger-ui.html

界面：

测试接口

一些常用注解

Api：标记类，说明类的作用，可以标记一个Controller类做为swagger 文档资源 @Api(value = "UserController", description = "userController") ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）ApiModelProperty：描述一个model的属性

ApiOperation：用在方法上，说明方法的作用 @ApiOperation(value = "findById") ApiParam ： 请求属性 public User findById(@PathVariable("id") @ApiParam(value = "userId", required = true) String id){} ApiResponse ： 响应配置，放在方法上

ApiResponses：响应集配置，可以设置多个@ApiResponse

---

knife4j强化Swagger

虽然Swagger很强，但有点丑，而且无法便捷导出接口文档，有需求就有市场，github就有对应的插件knife4j

knife4j完全遵循了springfox-swagger中的使用方式，并在此基础上做了增强功能

knife4j官方文档

快速开始

Maven导包（在Swagger的基础上，再导入knife4j包，版本） <!--整合Knife4j--> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <version>2.0.4</version> </dependency> 在swagger的配置类上添加@EnableKnife4j @EnableSwagger2 @Configuration @EnableKnife4j public class SwaggerConfig { }

当然，需要更细节的配置

@Bean(value = "defaultApi2") public Docket defaultApi2() { Docket docket=new Docket(DocumentationType.SWAGGER_2) .apiInfo(new ApiInfoBuilder() //.title("swagger-bootstrap-ui-demo RESTful APIs") .description("# swagger-bootstrap-ui-demo RESTful APIs") .termsOfServiceUrl("http://www.xx.com/") .contact("xx@qq.com") .version("1.0") .build()) //分组名称 .groupName("2.X版本") .select() //这里指定Controller扫描包路径 .apis(RequestHandlerSelectors.basePackage("com.htphy.wx.module.dev.controller")) .paths(PathSelectors.any()) .build(); return docket; } 启动Springboot，Knife4j网址为http://localhost:8080/doc.html

里面的下载功能很强大

还有很多优化的地方，具体看官方文档