springfox及springdoc

open api 简介

OpenApi是一个业界的 API 文档标准，一个规范，提供了一种标准的方式来描述API的结构、参数、响应等信息。springfox和springdoc是用在Spring框架中生成和展示OpenApi文档的工具

springfox

springfox基于Spring框架的库，提供注解，如@Api、@ApiOperation、@ApiParam等，通过配置和使用，可自动生成OpenApi文档
最新版本为17年发布的 Swagger3（Open Api3）

springdoc

也是基于Spring框架，与springfox比，更加轻量级，使用更简单，提供一些注解，如@OpenAPIDefinition、@Operation、@Parameter等

springfox和springdoc注解映射关系：

@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")
1
2
3
4
5
6
7
8
9
10

Swagger3使用方法

引入依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
1
2
3
4
5

配置swagger

@Configuration
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.luxifa"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("My API")
                .description("API documentation for My API")
                .version("1.0")
                .build();
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

RequestHandlerSelectors指定要包含在API文档中的控制器，PathSelectors指定要包含在API文档中的路径。apiInfo()方法用于设置API文档的标题、描述和版本号。

实体类

@Data
@ApiModel(description = "学生实体类")
public class Student {
    @ApiModelProperty(value = "学号")
	private String id;
	@ApiModelProperty(value = "姓名")
	private String name;
}
1
2
3
4
5
6
7
8

Controller层

@RestController
@RequestMapping("/stu")
@Api(value = "学生业务")
public class StuContoller {
    @ApiOperation(value = "保存学生信息")
    @PostMapping("/saveStu")
	public void save(Student stu) {
	
	}
}

1
2
3
4
5
6
7
8
9
10
11

接口访问地址：http://ip:端口/服务名/swagger-ui.html

springdoc使用方法

引入依赖

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.11</version>
</dependency>
1
2
3
4
5

配置文件中

springdoc.swagger-ui.path=/swagger-ui.html
1

Controller层

@Tag(name = "学生业务API")
public class StuController {
	@Operation(summary = "插入学生数据",description="插入学生数据的描述想信息")
	@Parameter(name ="stu",description = "学生参数的描述信息")
	@PostMapping("/saveStu")
	public void save(Student stu) {
	
	}
}
1
2
3
4
5
6
7
8
9

接口访问地址：http://ip:端口/服务名/swagger-ui.html
或者：http://ip:端口/服务名/swagger-ui/index.html

参考博客：
https://blog.csdn.net/qq_41787812/article/details/128627748
https://blog.csdn.net/u011943534/article/details/127220945