spring doc
阅读数:87 评论数:0
跳转到新版页面分类
python/Java
正文
一、swagger
在没有swagger之前，我们可以使用word、excel或其它在线文档来书写接口定义文档，但这有一个弊端，即在接口发生改变时需要及时同步接口文档。
作为一款非常流行的API文档生成规范，swagger最为方便的地方在于，只要项目集成了它，一启动就能生成最新版文档，而且能在线调试。
不过swagger有很多缺陷，可以使用knife4j来增强它。
swagger规范有主流的实现库是SpringFox和SpringDoc。
| @Api |
用在请求类上 参数： tags：说明该类的作用，参数是个数组，可以填多个 description：用户基本信息操作 |
| @ApiOperation |
用于方法，表示一个http请求访问该方法的操作 参数： value：方法的用途和作用 notes: 方法的注意事项和备注 |
| @ApiModel |
用于说明实体作用 参数： description="描述实体的作用" |
| @ApiModelProperty |
描述实体类的属性 参数： value：描述参数的意义 name: 参数的名称 required: true/false， 参数是否为必选 |
| @ApiImplictParams | 用于请求的方法上，包含多个@ApiImplictParam |
| @ApiImplictParam |
表示单独的请求参数 参数： name：参数名 value：参数说明 dataType：数据类型 header： 使用@RequestHeader获取参数 query： 使用@RequestParam获取参数 path： 使用PathVariable获取参数 defaultValue： 参数的默认值 required: true/false，参数是否必传 |
| @ApiParam |
用于方法，对参数的要求和说明 参数： name：参数名称 value：参数的简要说明 defaultValue：参数默认值 required: true/false，是否必填 |
| @ApiResponses |
用于请求的方法上，表示响应 一个@ApiResponses包含多个@ApiResponse |
| @ApiResponse |
用在请求的方法上，表示不同的响应 参数： code：响应码 message：响应信息 |
| @ApiIgnore |
用在类或者方法上，不被显示在页面上 |
二、SpringFox
SpringFox是swagger的一个开源实现，已经停止更新了，如果你使用SpringBoot 2.6.x以上的版本的，SpringFox就已经无法使用了，网上有文档称可以添加如下配置，个人并不尝试
spring:
mvc:
path match:
matching-strategy: ant_path_matcher
springfox-swagger是基于Spring生态系统的swagger规范的实现，springfox-swagger-ui是对swagger-ui的封装。
（1）swagger2需要导入两个资源依赖
#Swagger2资源依赖
<!-- 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>
（2）swagger3只需要导入一个资源依赖
# Swagger3资源依赖
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
http://springfox.github.io/springfox/docs/current/#quick-start-guides
@Configuration
@EnableSwagger2 // 2
// @EnableOpenApi // 3
public class Swagger2Config {
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2) // 2
// return new Docket(DocumentationType.OAS_30) // 3
.pathMapping("/")
.enable(true)
.host("localhost:8888")
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.record.controller"))
.paths(PathSelectors.any())
.build()
.protocols(newHashSet("https","http")) // 2
.securitySchemes(singletonList(apiKey()))
.securityContexts(singletonList(securityContext()));
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("京茶吉鹿")
.description("京茶吉鹿的Demo (SpringBoot2.5.5 + Swagger2.9.2)")
.contact(new Contact("京茶吉鹿", "http:localhost:8888/doc.html", "jc.jingchao@qq.com"))
.version("1.0.0")
.termsOfServiceUrl("http://localhost:8888")
.build();
}
private ApiKey apiKey(){
return new ApiKey("Authorization", "Authorization", "Header");
}
private SecurityContext securityContext(){
return SecurityContext.builder()
.securityReferences(defaultAuth())
.forPaths(PathSelectors.regex("/hello/.*"))
.build();
}
List<SecurityReference> defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
return singletonList(
new SecurityReference("Authorization", authorizationScopes));
}
}
访问路径 ：
-
Swagger2.9.2 http://localhost:8888/swagger-ui.html
-
Swagger3.0.0 http://localhost:8888/swagger-ui/index.html
三、SpringDoc
SpringDoc是最近才流行起来的Swagger实现库，它不仅支持SpringMVC，还支持Spring WebFlux。
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.6.6</version>
</dependency>
<!--Knife4j的Swagger皮肤依赖-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-springdoc-ui</artifactId>
<version>3.0.3</version>
</dependency>
@Configuration
public class OpenApiConfig {
@Bean
public OpenAPI springShopOpenAPI() {
//鉴权组件(随便起名的)
SecurityScheme securityScheme = new SecurityScheme()
.type(SecurityScheme.Type.HTTP)
.scheme("bearer")//固定写法
.bearerFormat("JWT")
.in(SecurityScheme.In.HEADER)
.name("Authorization");
Components components = new Components()
.addSecuritySchemes("bearer-jwt", securityScheme);
//鉴权限制要求(随便起名的)
SecurityRequirement securityRequirement = new SecurityRequirement()
.addList("bearer-jwt", Arrays.asList("read", "write"));
return new OpenAPI()
.info(new Info().title("医院管理系统 API")
.description("Spring HIS application")
.version("v0.0.1"))
.components(components)
.addSecurityItem(securityRequirement)
;
}
}
@Api -> @Tag
@ApiIgnore -> @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
@ApiImplicitParam -> @Parameter
@ApiImplicitParams -> @Parameters
@ApiModel -> @Schema
@ApiModelProperty(hidden = true) -> @Schema(accessMode = READ_ONLY)
@ApiModelProperty -> @Schema
@ApiOperation(value = "foo", notes = "bar") -> @Operation(summary = "foo", description = "bar")
@ApiParam -> @Parameter
@ApiResponse(code = 404, message = "foo") -> @ApiResponse(responseCode = "404", description = "foo")
四、Knife4j
knife4j是swagger-ui的增强库，前身是swagger-bootstrap-ui. Knife4j的默认接口文档地址：http://localhost:8088/doc.html
（1）支持spring boot 3
（2）兼容适配springdoc-openapi
（3）提供官方docker镜像
（1）引入starter
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>4.0.0</version>
</dependency>（2）配置
Knife4j只提供了增加部分，如果要启用Knife4j的增强功能，可以在配置文件中进行开启。
# springdoc-openapi项目配置
springdoc:
swagger-ui:
path: /swagger-ui.html
tags-sorter: alpha
operations-sorter: alpha
api-docs:
path: /v3/api-docs
group-configs:
- group: 'default'
paths-to-match: '/**'
packages-to-scan: com.xiaominfo.knife4j.demo.web
# knife4j的增强配置，不需要增强可以不配
knife4j:
enable: true
setting:
language: zh_cn
若给接口文档设置一个查看权限，可以
knife4j:
# 开启增强配置
enable: true
# 开启Swagger的Basic认证功能,默认是false
basic:
enable: true
# Basic认证用户名
username: test
# Basic认证密码
password: 123