Swagger2介绍
前后端分离开发模式中，api文档是最好的沟通方式。
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
- 及时性 (接口变更后，能够及时准确地通知相关前后端开发人员)
- 规范性 (并且保证接口的规范性，如接口的地址，请求方式，参数及响应格式和错误信息)
- 一致性 (接口信息一致，不会出现因开发人员拿到的文档版本不一致，而出现分歧)
- 可测性 (直接在接口文档上进行测试，以方便理解业务)
Demo 简单使用
配置Swagger2：
1、相关依赖
<!--swagger--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>your version</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>your version</version> </dependency>
2、创建Swagger2配置文件：
import com.google.common.base.Predicates; 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.service.ApiInfo; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 public class Swagger2Config { @Bean public Docket webApiConfig(){ return new Docket(DocumentationType.SWAGGER_2) .groupName("webApi") .apiInfo(webApiInfo()) .select() .paths(Predicates.not(PathSelectors.regex("/admin/.*"))) .paths(Predicates.not(PathSelectors.regex("/error.*"))) .build(); } @Bean public Docket adminApiConfig(){ return new Docket(DocumentationType.SWAGGER_2) .groupName("adminApi") .apiInfo(adminApiInfo()) .select() .paths(Predicates.and(PathSelectors.regex("/admin/.*"))) .build(); } private ApiInfo webApiInfo(){ return new ApiInfoBuilder() .title("网站-课程中心API文档") .description("本文档描述了课程中心微服务接口定义") .version("1.0") .contact(new Contact("Helen", "http://www.baidu.com", "55317332@qq.com")) .build(); } private ApiInfo adminApiInfo(){ return new ApiInfoBuilder() .title("后台管理系统-用户中心API文档") .description("本文档描述了后台管理系统课程中心微服务接口定义") .version("1.0") .contact(new Contact("Helen", "http://www.baidu.com", "55317332@qq.com")) .build(); } }
3、重启服务器查看接口
http://localhost:post/swagger-ui.html
4、API模型
MP的代码生成器已经在 entity 的实体类中生成了模型的定义
实体类 Entity 上注解：
@ApiModel(value="Teacher对象", description="用户")
实体类 Entity 属性上注解
@ApiModelProperty(value = "...")
可以添加一些自定义设置，例如：
定义样例数据
@ApiModelProperty(value = "创建时间", example = "2019-01-01 8:00:00") @TableField(fill = FieldFill.INSERT) private LicalDate gmtCreate; @ApiModelProperty(value = "更新时间", example = "2019-01-01 8:00:00") @TableField(fill = FieldFill.INSERT_UPDATE) private Date gmtModified;
5、定义接口说明和参数说明
定义在类上：@Api
定义在方法上：@ApiOperation
定义在参数上：@ApiParam
@Api(description = "用户管理") @RestController @RequestMapping("/admin/user") public class UserAdminController { @Autowired private SysUserService sysUserService; @ApiOperation(value = "所有讲师列表") @GetMapping public List<User> list() { return sysUserService.list(null); } @ApiOperation(value = "根据ID删除用户") @DeleteMapping("/{id}") public boolean removeById( @ApiParam(name = "id", value = "用户ID", required = true) @PathVariable String id) { return sysUserService.removeById(id); } }
常用注解：
1@Api() // 用于类； // 表示标识这个类是swagger的资源 2@ApiOperation() // 用于方法； // 表示一个http请求的操作 3@ApiParam() // 用于方法，参数，字段说明； // 表示对参数的添加元数据（说明或是否必填等） 4@ApiModel() // 用于类 // 表示对类进行说明，用于参数用实体类接收 5@ApiModelProperty() // 用于方法，字段 // 表示对model属性的说明或者数据操作更改 6@ApiIgnore() // 用于类，方法，方法参数 // 表示这个方法或者类被忽略 7@ApiImplicitParam() // 用于方法 // 表示单独的请求参数 8@ApiImplicitParams() // 用于方法，包含多个 @ApiImplicitParam // 具体使用举例说明： @Api() // 用于类；表示标识这个类是swagger的资源 tags // 表示说明 value // 也是说明，可以使用tags替代但是tags如果有多个值，会生成多个list