Swagger3.X和2.X—从⼊门到实战
Swagger 3.X
OpenApi规范
接⼝⽂档
谁产⽣：接⼝开发⼈员，后端⼯程师
谁维护：接⼝开发⼈员，后端⼯程师
谁使⽤：前端同学、测试同学、产品经理
接⼝存在的问题：
接⼝⽂档不存在，靠抓包获取
接⼝更换后不及时更新
接⼝⽂档写错，注解写错
⾃动⽣成⽂档⼯具在跨语⾔不兼容
OpenApi规范：声明了⽤于⽂档的规范的版本
地址：
OpenAPI规范经过Reverb Technologies和SmartBear等公司多年的发展，OpenAPI计划拥有该规范（捐赠之后），OpenAPI Initiative在GitHub上托管社区驱动的规范。
规范是⼀种与语⾔⽆关的格式，⽤于描述RESTful Web服务，应⽤程序可以解释⽣成的⽂件，这样才能⽣成代码、⽣成⽂档并根据其描述的服务创建模拟应⽤。
开放API规范（OAS）是⼀种⽆需编写实际API代码就可以记录API的⽅法。这是⼀种开放源代码格式，可以⽤来描述API。在此过程中，我们可以使⽤JSON或YAML格式。OpenAPI⽂档有三个必需的部分或对象，也可以增加其他模块：
1. openapi - OpenAPI规范版本的语义版本号
2. info - 有关API的元数据
3. paths - API的可⽤路径和操作
Api⽂档管理⼯具对⽐
ApiDoc
地址：
github:
简介：源代码中的注释直接⾃动⽣成api接⼝⽂档的⼯具
优点：不⼊侵代码、⽀持跨语⾔使⽤、界⾯友好简洁
缺点：依赖环境 node/npm
⽰例：在代码⾥⾯增加注释使⽤
/**
* @apiGroup Product
* @api {GET} /product/{id} 查询⼀个产品
* @apiDescription 接⼝描述xxx
* @apiParam {String} id 产品id(必填*)
* @apiSuccessExample SuccessExample
* HTTP/1.1 200
* {
* id: 'xxx',
* name: 'xxx',
* desc: 'xxxx'
* }
* @apiErrorExample ErrorExample
*/
restful接口调用实例
@GetMapping("/{id}")
public Product detail(@PathVariable String id){
return JsonData.buildSuccess();
}
Swagger 丝袜哥
地址：
简介：在java代码⾥⾯增加注解⽣成接⼝⽂档
优点：⽀持SpringBoot等主流Java框架、对java代码友好、界⾯简洁、国内⽐较活跃，主要是spring社区带动、功能⽐较多缺点：对跨语⾔⽀持不友好（可以和knife4j整合解决这个问题）、代码需要引⼊相关依赖包和配置、⽂档相对缺少
⽰例：在代码⾥⾯增加注解
RestController
@RequestMapping("/api/v1/user")
@Api(tags = "⽤户模块",value = "⽤户UserController")
public class UserController {
@Autowired
private BannerService bannerService;
@ApiOperation("分页⽤户列表")
@GetMapping("list")
public JsonData list(){
List<BannerDO> list = bannerService.list();
return JsonData.buildSuccess(list);
}
}
Swagger3快速⼊门
springfox3.0 已经⽀持swagger3了，之前SpringFox未⽀持 OpenAPI3 标准使⽤的是springdoc-openapi-ui依赖
1、创建SpringBoot项⽬，并确保项⽬能够正确运⾏。
2、导⼊相关maven依赖（对⽐Swagger2，Swagger3只需要导⼊⼀个依赖即可）：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
3、Swagger3配置类
/**
* @EnableOpenApi：开启Swagger3的注解。与Swagger2启动注解不同@EnableSwagger2
* @EnableOpenApi 不配置也可以
*/
@EnableOpenApi
@Configuration
public class Swagger3Config {
}
4、访问swagger3-ui地址：
Swagger3配置详解
application.properties配置⽂件
# 项⽬名称
spring.application.name=Swagger3.x api
>># ⾃定义swagger配置 >>#
# 是否开启swagger，开发环境打开，线上关闭
# 项⽬名称：enable
# 项⽬版本信息：application-version
# 项⽬描述信息：application-description
swagger.application-name= ${spring.application.name}
swagger.application-version=1.0
swagger.application-description=Swagger3.x api info
Swagger配置类
/**
* @EnableOpenApi：开启Swagger3的注解。与Swagger2启动注解不同@EnableSwagger2
* 默认不配置也可以
*/
@EnableOpenApi
@Configuration
public class Swagger3Config {
/**
* 是否开启swagger，⽣产环境⼀般关闭，所以这⾥成变量
*/
@Value("${able}")
private Boolean enable;
/**
* 项⽬应⽤名
*/
@Value("${swagger.application-name}")
private String applicationName;
/
**
* 项⽬版本信息
*/
@Value("${swagger.application-version}")
private String applicationVersion;
/**
* 项⽬描述信息
*/
@Value("${swagger.application-description}")
private String applicationDescription;
/**
* 配置了Swagger的Docket的bean实例：Swagger3 需要配置成 DocumentationType.OAS_30
* enable()：是否启动Swagger，如果为False，则Swagger不能在浏览器中访问
* apiInfo()：配置api⽂档元信息
* select()：选择哪些接⼝作为swagger的doc发布，⼀般和apis()⼀起使⽤
* apis(RequestHandlerSelectors.XXX)：配置要扫描的⽅式
* RequestHandlerSelectors.basePackage()：指定要扫描的包
* RequestHandlerSelectors.any()：扫描全部
* ()：不扫描
* RequestHandlerSelectors.withClassAnnotation()：扫描类上的注解，参数是注解的反射对象
* RequestHandlerSelectors.withMethodAnnotation()：扫描⽅法上的注解，参数是注解的反射对象
* 例如：RequestHandlerSelectors.withClassAnnotation(ApiOperation.class)
* paths()：过滤什么路径，⼀般跟在select()之后，根据请求路径定义当前Docket需要包含控制器的哪些⽅法。
* ()：不扫描
* PathSelectors.any()：扫描所有请求路径
* PathSelectors.ant("/*")：匹配Ant样式的路径模式
* ("/cat/.*")：匹配正则指定的正则表达式路径
* pathMapping()：默认请求都是以 / 根路径开始.如果我们的应⽤不是部署在根路径，
* ⽐如以/platform 部署，则可以通过⼀下⽅式设置请求的统⼀前缀。最终调⽤接⼝后会和paths拼接在⼀起. * 如接⼝为：/v1/api/list，那么swagger-ui页⾯则显⽰/platform/v1/api/list
*
* build：⼯⼚模式
* 注意：Docket.select().xxx.build()必须⼀起使⽤
* select() 返回的是⼀个ApiSelectorBuilder对象，⽽我们需要的却是Docket对象，
* 因此，ApiSelectorBuilder类中提供了⼀个⽅法 --> build() ⽅法返回的是⼀个Docket对象。
*/
@Bean
public Docket docket() {
return new Docket(DocumentationType.OAS_30)
.enable(enable)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.
build()
.pathMapping("/");
}
/**
* ApiInfo：主要返回接⼝和接⼝创建者的信息
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title(applicationName)
.description(applicationDescription)
.contact(new Contact("lsx", "wwwblogs/liusuixing/", "8629303@qq"))
.
version(applicationVersion)
.build();
}
}
分组配置：（其他配置都是⼀样的）
@Bean
public Docket docketA(){
return new Docket(DocumentationType.OAS_30).groupName("A");
}
@Bean
public Docket docketB(){
return new Docket(DocumentationType.OAS_30).groupName("B");
}
Swagger3常⽤注解
注解作⽤
@Api⽤在Controller类上，对所标注的类进⾏描述说明。
@ApiOperation⽤在COntroller类中的⽅法上，对所标注的⽅法进⾏描述说明。@ApiImplicitParams、@ApiImplicitParam⽅法的参数的说明；@ApiImplicitParams ⽤于指定单个参数的说明@ApiParam⽤于 Controller 中⽅法的参数说明。
@ApiResponse、@ApiResponses⽅法返回值的说明；@ApiResponses ⽤于指定单个参数的说明@ApiModel、@ApiModelProperty⽤在实体类和属性上，对实体类和属性进⾏说明@ApiIgnore⽤在类、⽅法，参数中⽤来屏蔽某接⼝或参数，使其不在页⾯上显⽰
@Api：⽤在请求的类上，表⽰对类的说明（不配置默认是按类名驼峰变下划线显⽰）
value：表⽰说明
tags：也是说明，可以替代或者覆盖value，tags如果有多个值，会⽣成多个list
description：对api资源的描述
basePath：基本路径
position：如果配置多个Api 想改变显⽰的顺序位置
produces：如 “application/json, application/xml”
consumes：如 “application/json, application/xml”
protocols：协议类型，如: http, https, ws, wss.
authorizations：⾼级特性认证时配置
hidden：配置为true ，将在⽂档中隐藏
@ApiOperation：⽤在请求的⽅法上，说明⽅法的⽤途、作⽤
value：⽤于⽅法描述
tags：可以重新分组（视情况⽽⽤）
notes：⽤于提⽰内容
@ApiImplicitParams：⽤在请求的⽅法上，表⽰⼀组参数说明
@ApiImplicitParam：⽤在@ApiImplicitParams注解中，指定⼀个请求参数的各个⽅⾯
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地⽅
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（⽤于restful接⼝）--> 请求参数的获取：@PathVariable
·
div（不常⽤）
· form（不常⽤）
dataType：参数类型，默认String，其它值dataType="Integer"
defaultValue：参数的默认值
@ApiParam() ⽤于⽅法，参数，字段说明；表⽰对参数的添加元数据（说明或是否必填等）
name：参数名
value：参数说明
required：是否必填
defaultValue：默认值
@ApiResponses：⽤在请求的⽅法上，表⽰⼀组响应
@ApiResponse：⽤在@ApiResponses中，⼀个@ApiResponse表⽰⼀种响应信息
responseCode：字符串，例如"400"
description：信息，例如"请求参数没填好"
@ApiModel：⽤于响应类上，表⽰⼀个返回响应数据的信息
（这种⼀般⽤在post创建的时候，使⽤@RequestBody这样的场景，请求参数⽆法使⽤@ApiImplicitParam注解进⾏描述的时候） value：⾃定义类的名称
description：为类添加长⽂本描述信息
@ApiModelProperty：⽤在属性上，描述响应类的属性
value：定义参数描述信息
name：定义参数名称
required：是否必填
实例：
ller;
del.ApiResult;
del.User;
import io.swagger.annotations.*;
import io.swagger.v3.sponses.ApiResponse;
import io.swagger.v3.sponses.ApiResponses;
import org.springframework.web.bind.annotation.*;
@Api(tags = "⽤户模块" ,description = "User module")
@RestController
@RequestMapping("/user")
public class UserController {
/**
* 参数形式⼀：@ApiImplicitParams、@ApiImplicitParam
*/
@ApiOperation(value = "新增⽤户A", notes = "添加新的⽤户", tags = "⽤户模块",httpMethod = "POST")
@ApiImplicitParams({
@ApiImplicitParam(name = "name", value = "⽤户名", required = true, dataType = "String"),
@ApiImplicitParam(name = "age", value = "年龄", required = true, dataType = "Integer"),
@ApiImplicitParam(name = "email", value = "邮箱", required = true, dataType = "String")
})
@ApiResponses({
@ApiResponse(responseCode = "200", description = "保存成功"),
@ApiResponse(responseCode = "400", description = "保存失败")
})
@PostMapping("/swagger3AnnotationA")
public ApiResult swagger3AnnotationA(@RequestParam("name") String name,
@RequestParam("age") Integer age,
@RequestParam("email") String email){
return ApiResult.builder().code(200).message("返回成功").build();
}
/**
* 参数形式⼆：@ApiParam
*/
@ApiOperation(value = "新增⽤户B", notes = "添加新的⽤户", tags = "⽤户模块",httpMethod = "POST")
@ApiResponses({
@ApiResponse(responseCode = "200", description = "保存成功"),
@ApiResponse(responseCode = "400", description = "保存失败")
})
@PostMapping("/swagger3AnnotationB")
public ApiResult swagger3AnnotationB(
@ApiParam(name = "name", value = "⽤户名") @RequestParam("name") String name,
@ApiParam(name = "age", value = "年龄")@RequestParam("age") String age,
@ApiParam(name = "email", value = "邮箱")@RequestParam("email") String email){
return ApiResult.builder().code(200).message("返回成功").build();
}
/
**
* 参数形式三：@ApiModel、@ApiModelProperty
*/
@ApiOperation(value = "新增⽤户C", notes = "添加新的⽤户", tags = "⽤户模块",httpMethod = "POST")
@ApiResponses({
@ApiResponse(responseCode = "200", description = "保存成功"),
@ApiResponse(responseCode = "400", description = "保存失败")
})
@PostMapping("/swagger3AnnotationC")
public ApiResult swagger3AnnotationC(@RequestBody User user){
return ApiResult.builder().code(200).message("返回成功").data(user).build();
}
}
resttemplate用法
« 上一篇
flink restful api获取指标
下一篇 »
发表评论