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")

Swagger3使用方法

引入依赖

<dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version>
</dependency>

配置swagger

@Configuration
@EnableOpenApi
public class SwaggerConfig {@Beanpublic 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();}
}

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

实体类

@Data
@ApiModel(description = "学生实体类")
public class Student {@ApiModelProperty(value = "学号")private String id;@ApiModelProperty(value = "姓名")private String name;
}

Controller层

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

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

springdoc使用方法

引入依赖

<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-ui</artifactId><version>1.6.11</version>
</dependency>

配置文件中

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

Controller层

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