springdoc-openapi 简介

springdoc-openapijava库有助于运用 spring boot 项目主动生成 API 文档。springdoc-openapi经过在运行时查看应用程序以根据 spring 装备、类结构和各种注释揣度 API 语义来作业。

主动生成 JSON/YAML 和 HTML 格局 API 的文档。能够运用 swagger-api 注释经过注释来完成此文档。

该库支撑:

  • OpenAPI3
  • SpringBoot (v1, v2 and v3)
  • JSR-303, specifically for @NotNull, @Min, @Max, and @Size.
  • Swagger-ui
  • OAuth 2
  • GraalVM 原生镜像

为什么运用 springdoc-openapi

因为之前项目一直运用的是springfox3.0来集成swagger管理API接口文档,但目前springfox现已中止保护了。最近在晋级底层结构时看到spring官方引荐运用springdoc,在自己一步一步查找相关资料时,发现国内关于这块的参阅资料较少,也不全面。故写此篇文章来协助大家快速集成。

Knife4j简介

Knife4j是一个集Swagger2OpenAPI3为一体的增强处理方案。

开端集成

Maven引进

首先在maven里引进springdoc-openapi

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

注释的差异

这儿需求留意,咱们要用swagger3注释替换swagger2注释(它现已包含在springdoc-openapi-ui依赖项中)。swagger 3 注释的包是io.swagger.v3.oas.annotations

@Api -> @Tag
@ApiIgnore -> @Parameter(hidden = true)@Operation(hidden = true)@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")

以下举几个简单的:

Controller:

@Tag(name = "用户接口")
@RestController
@RequestMapping("sys/user")
public class SysUserController {
    @Resource
    private ISysUserService sysUserService;
    @Operation(summary = "分页查询")
    @GetMapping("page")
    public AjaxResult queryPage(@ParameterObject SysUserPageDTO dto) {
        PageInfo page = sysUserService.queryPage(dto);
        return AjaxResult.success(page);
    }
    @Operation(summary = "详情")
    @GetMapping("{id}")
    public AjaxResult queryInfo(@PathVariable Long id) {
        SysUserDTO dto = sysUserService.queryById(id);
        return AjaxResult.success(dto);
    }
    @Operation(summary = "新增")
    @PostMapping
    public AjaxResult save(@RequestBody SysUserDTO dto) {
        Long id = sysUserService.saveInfo(dto);
        return AjaxResult.success(id);
    }
}

POST恳求的DTO:

@Schema(description = "用户 数据传输目标")
@Data
@Accessors(chain = true)
public class SysUserDTO implements Serializable {
    @Schema(description = "ID")
    private Long id;
    @Schema(description = "用户名")
    private String userName;
    @Schema(description = "实在名字")
    private String realName;
    @Schema(description = "暗码")
    private String password;
    @Schema(description = "性别(0男,1女)")
    private Integer sex;
    @Schema(description = "电话号码")
    private String phone;
    @Schema(description = "状态(0停用,1正常)")
    private Integer status;
}

❗ 假如你运用一个目标来封装你GET恳求的参数,会将你的参数封装为一个json,这不是咱们想要的:

【超详细】springboot + springdoc-openapi + knife4j 集成案例

要处理这样的问题,有两种处理办法(感谢@nano发现及处理的问题):

办法一(引荐):

在官方文档里有这么一句话:“假如您运用一个目标来捕获多个恳求查询参数,请注释该办法参数 @ParameterObject”。所以你应该在你get恳求封装的目标前加注解 @ParameterObject,同时应该在目标里的参数注解运用 @Parameter,而不是 @Scheme

GET接口:

@Operation(summary = "分页查询")
@GetMapping("page")
public AjaxResult queryPage(@ParameterObject SysUserPageDTO dto) {
    PageInfo page = sysUserService.queryPage(dto);
    return AjaxResult.success(page);
}

GET恳求封装的DTO:

@Data
@EqualsAndHashCode(callSuper = true)
@Accessors(chain = true)
public class SysUserPageDTO extends BasePageDTO {
    @Parameter(description = "用户名")
    private String username;
}

办法二(不引荐):

增加装备(增加此装备后,就不需求增加额外的@ParameterObject@Parameter注解):

❗ 注:这个装备在最新版(1.6.15)有个bug,当你运用这个装备今后再用@Valid注解,装备会失效,待官方处理,所以引荐办法一(PS:官方已修正了该问题,下个版别应该会处理)。

spring-doc:
    default-flat-param-object: true

装备

装备文件,更多装备请看:springdoc 中心装备

springdoc:
  api-docs:
    # 是否敞开接口文档
    enabled: true
  swagger-ui:
    # 耐久化认证数据,假如设置为 true,它会保存授权数据而且不会在浏览器关闭/刷新时丢掉
    persistAuthorization: true

装备文档:

❗ 这儿我更引荐将文档标题、作者等信息写到application里,然后经过@ConfigurationProperties引进,会更高雅

@Configuration
@AutoConfigureBefore(SpringDocConfiguration.class)
public class OpenApiConfig {
    private static final String TOKEN_HEADER = "Authorization";
    @Bean
    public OpenAPI openApi() {
        return new OpenAPI()
                .components(
                        new Components().addSecuritySchemes(TOKEN_HEADER,
                                new SecurityScheme()
                                        .type(SecurityScheme.Type.APIKEY)
                                        // 这儿装备 bearer 后,你的恳求里会主动在 token 前加上 Bearer
                                        .scheme("bearer")
                                        .bearerFormat("JWT")
                        ).addParameters(TOKEN_HEADER,
                                new Parameter()
                                        .in("header")
                                        .schema(new StringSchema())
                                        .name(tokenHeader)
                        ))
                .info(
                        new Info()
                                .title("文档标题")
                                .description("文档描绘")
                                .contact(new Contact().name("作者").email("邮箱").url("能够写你的博客地址或不填"))
                                // 参阅 Apache 2.0 答应及地址,你能够不配此项
                                .license(new License().name("Apache 2.0").url("https://www.apache.org/licenses/LICENSE-2.0.html"))
                                .version("0.1")
                )
                // 引进外部的文档,我这儿引得是 springdoc 官方文档地址,你能够不配此项
                .externalDocs(new ExternalDocumentation()
                        .description("SpringDoc Full Documentation")
                        .url("https://springdoc.org/")
                );
    }
    /**
     * GroupedOpenApi 是对接口文档分组,类似于 swagger 的 Docket
     * 
     * @return
     */
    @Bean
    public GroupedOpenApi authApi() {
        return GroupedOpenApi.builder()
                // 组名
                .group("认证接口")
                // 扫描的途径,支撑通配符
                .pathsToMatch("/login")
                // 扫描的包
                .packagesToScan("com.demo.controller.auth")
                .build();
    }
    @Bean
    public GroupedOpenApi sysApi() {
        return GroupedOpenApi.builder()
                .group("体系接口")
                .pathsToMatch("/sys/**")
                // 增加自定义装备,这儿增加了一个用户认证的 header,否则 knife4j 里会没有 header
                .addOperationCustomizer((operation, handlerMethod) -> operation.security(
                        Collections.singletonList(new SecurityRequirement().addList(TOKEN_HEADER)))
                )
                .build();
    }
}

拜访文档

装备完成之后,就能够拜访文档地址:http://localhost:${port}/${context-path}/swagger-ui/html.index

❗ 假如你加入了拦截器或引进了spring-security等权限结构,需求放通文档地址及静态资源:

- /**/*.html
- /**/*.css
- /**/*.js
- /**/api-docs/**

至此一个简单的接口文档就生成了,是不是很简单

【超详细】springboot + springdoc-openapi + knife4j 集成案例

集成knife4j

Maven引进

maven里引进knife4j

❗ 在knife4j@4.1.0里现已引进了springfox-openapi-ui@1.6.15,留意jar包抵触。

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
    <version>4.1.0</version>
</dependency>

❗ 假如你运用的是SpringBoot3,需求留意:

  • Spring Boot 3 只支撑OpenAPI3标准
  • Knife4j供给的starter现已引证springdoc-openapi的jar,开发者需留意避免jar包抵触
  • JDK版别有必要 >= 17

而且需求引进这个包:

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.0.0</version>
</dependency>

拜访文档地址

然后你就能够直接拜访文档地址了:http://localhost:${port}/${context-path}/doc.html

【超详细】springboot + springdoc-openapi + knife4j 集成案例

至此咱们就集成完了,有其他疑问欢迎在评论区提出来