官网地址
Swagger是一个用于 生成、描述、调用 RESTful 接口的Web服务,
可以将项目中对外暴露的接口展现在Web页面上,并且可以进行接口的调用和调试,代替Postman
作用和好处:
- 跟随项目代码,编译时动态实时生成新的接口文档可以将指定的接口,展现在web文档页面可以直接进行接口调试,降低开发阶段成本
tips:
- 所有使用方法均为注解,且均已Apixxx开头所有注解只会存在于Controller层和Model层
建议:不要使用最新版3.0.0+,会有兼容问题
一、依赖- 遵循 OpenApi 规范的core库
io.springfox springfox-swagger22.9.2
- Swagger UI库
io.springfox springfox-swagger-ui2.9.2
- 版本兼容
swagger 2.9.2版本自带的models库,版本未1.5.20,该版本会有一个警告一直抛出在控制台,于是我们需要排除错误版本,引入 1.5.22版本来解决这个问题
java.lang.NumberFormatException: For input string: ""
最后展示一下最终依赖:
二、启动项配置io.springfox springfox-swagger22.9.2 io.swagger swagger-modelsio.swagger swagger-models1.5.22 io.springfox springfox-swagger-ui2.9.2
package com.a2j.swagger; 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.service.Contact; import springfox.documentation.spi.documentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 // 开启Swagger web服务 public class SwaggerApiConfig { @Bean public Docket swagger() { return new Docket(documentationType.SWAGGER_2) .apiInfo(apiInfo()) // Api配置 .groupName("a2j模块") // 分组名称 .select() // 构建选择器builder配置 .apis(RequestHandlerSelectors.basePackage("com.a2j.controller")) // 扫描接口的包路径 .paths(PathSelectors.any()) // 扫描路径 .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("A2J-Api接口文档") .description("接口描述、参数描述、字段描述、在线调试") .version("1.0.0") .contact(new Contact("bzb", "", "")) .build(); } }
此时使用 http://localhost:1234/swagger-ui.html 访问就能看到文档了!
使用 一、类注解@Api
作用于`Controller`层的接口类,描述接口信息 常用参数: `tags`
@ApiModel
作用于`Model`层的实体类VO对象,描述对象信息 配合 `@ApiImplicitParams` 和 `@RequestBody`使用 常用参数:`description`
@ApiOperation
作用于`Controller`层的接口方法上,描述接口信息 常用参数:`value`、`notes`
value 该接口作用说明,直接UI呈现notes 备注,适合接口的详细描述response 返回值类型的.class
@ApiImplicitParam
@ApiImplicitParams
作用于`Controller`层的接口方法上,描述入参数据信息 `@ApiImplicitParam` 用于参数类型为`基础数据`的时候 `@ApiImplicitParams` 用于参数类型为`实体类对象`类型的时候 常用参数:`value`、`notes`
name 参数名
value 参数说明
required 是否为必传参数,默认false
paramType 入参方式,header/query/path/body
dataType 参数类型,默认String,int/String
defaultValue 参数默认值
@ApiResponse
@ApiResponses
作用于`Controller`层的接口方法上,描述出参数据信息。此功能最后有全局处理的方式优化。 `@ApiResponse` 用于描述单个响应码 `@ApiResponses` 用于描述多个响应码 常用参数:`code`、`message`
code 响应码
message 响应码的对应说明
response 可能抛出异常的数据类型的.class
三、属性字段注解@ApiModelProperty
作用于`Model`层的属性上,描述字段信息 常用参数:`value`
value 属性说明
required 是否必传,默认true
example 默认值
hidden 隐藏显示,默认false
使用案例:package com.a2j.controller.car; import io.swagger.annotations.*; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.*; ... @RestController @RequestMapping("/carType") @Api(tags = "车型接口") public class CarTypeController { @Autowired CarTypeService service; @PostMapping("/addCarType") @ApiOperation(value = "新增车型") @ApiImplicitParams({}) @ApiResponse(code = 200, message = "请求成功") public baseBeanApiResponse优化addCarType(@RequestBody CarTypeVO record) { service.addCarType(record); return baseBean.success(ResponseCode.SUCCESS); } @PutMapping("/delCarType/{id}") @ApiOperation(value = "删除车型") @ApiImplicitParam(name = "id", value = "车型id", required = true, dataType = "int", paramType = "path", defaultValue = "100") @ApiResponses({ @ApiResponse(code = 200, message = "请求成功"), @ApiResponse(code = 404, message = "接口不存在") }) public baseBean delCarType(@PathVariable Integer id) { service.delCarType(id); return baseBean.success(ResponseCode.SUCCESS); } } package com.a2j.beans.car.type; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import lombok.AllArgsConstructor; import lombok.Builder; import lombok.Data; import lombok.NoArgsConstructor; @Data @Builder @NoArgsConstructor @AllArgsConstructor @ApiModel(description = "车型出入参对象") public class CarTypeVO { @ApiModelProperty(value = "品牌id", hidden = true) private Integer brandId; @ApiModelProperty(value = "车系名称", required = true, example = "迈凯伦") private String typeName; ... }
上面我们介绍了 @ApiResponse 的使用方法 对于接口返回描述,每个接口都去加上同样的内容过于繁琐,于是我们使用全局的响应码配置处理。
@Bean public Docket swagger() { // 全局响应码统一处理 ListKnife4j优化SwaggerresponseMessages = new ArrayList<>(); for (ResponseCode value : ResponseCode.values()) { // 大于1000的不对外显示 if (value.getCode() > 1000) continue; responseMessages.add( new ResponseMessageBuilder() .code(value.getCode()) .message(value.getMessage()) .build() ); } return new Docket(documentationType.SWAGGER_2) .useDefaultResponseMessages(false) // 不使用默认的响应码描述 .globalResponseMessage(RequestMethod.GET, responseMessages) .globalResponseMessage(RequestMethod.POST, responseMessages) .globalResponseMessage(RequestMethod.PUT, responseMessages) .globalResponseMessage(RequestMethod.DELETE, responseMessages); }
Knife4j是Swagger的UI增强版,
Swagger现有的体验有如下缺陷,所以我们需要升级增强版 Knife4j
1. 文档界面粗糙,不易 *** 作 入参对象属性过多时阅读性差,在线调试不够友好 2. 正式环境无法关闭文档 Swagger有解决方案,但不是自有配置一、在pom.xml中改造依赖如下:
第一层级二、对启动配置项修改第二层级 com.github.xiaoymin knife4j-dependencies2.0.8 pom import com.github.xiaoymin knife4j-spring-boot-starterio.springfox springfox-swagger-ui
@EnableSwagger2 修改为:@EnableSwagger2WebMvc
原来的: import springfox.documentation.swagger2.annotations.EnableSwagger2; // http://localhost:1234/swagger-ui.html @Configuration @EnableSwagger2 // 开启Swagger web服务 public class SwaggerApiConfig { } 现在的: import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc; // http://localhost:1234/doc.html @Configuration @EnableSwagger2WebMvc // 开启Swagger web服务 public class SwaggerApiConfig { }
application-dev.yml增加配置
# knife4j knife4j: enable: true # 开启增强模式,下面高级设置才生效 production: false # 是否为生产环境 basic: enable: true # 开启knife4j username: bzb password: 123
application-prod.yml增加配置
# knife4j knife4j: enable: true # 开启增强模式,下面高级设置才生效 production: true # 是否为生产环境 basic: enable: true # 开启knife4j username: bzb password: 123
至此,配置就结束了,此时文档的访问地址为 http://localhost:1234/doc.html ,快去看看惊艳到你了没吧!
欢迎分享,转载请注明来源:内存溢出
评论列表(0条)