一文了解Spring boot + open api 3.0 + knife4j的集成实例,提供开发时常用的API配置

6 篇文章 0 订阅





API文档集成与增强

Knife4j是一个集Swagger2 和 OpenAPI3为一体的增强解决方案

集成open api

官网文档: springdoc-openapi

  1. 依赖导入
<dependency>
	<groupId>org.springdoc</groupId>
	<artifactId>springdoc-openapi-ui</artifactId>
	<version>1.6.11</version>
</dependency>

  1. 配置文件设置
# open api配置
springdoc:
  packages-to-scan: com.example.swagger3knife4j.controller
  swagger-ui:
    enabled: true
  api-docs:
    enabled: true

  1. 文档设置
@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI api() {
        return new OpenAPI().info(new Info().title("文档标题")
                .description("文档描述")
                .version("v1.0.0"));
    }
}

到此配置就完成了,接下来便是使用open api的规范来生成对应的API文档





open api使用方法

  1. 首先通过@Tag给文档添加注释,通过@Operation给每个接口添加文档注释
@Tag(name = "用户接口")
@RestController
@RequestMapping(PRIVATE_PATH + "/user")
public class UserController {

    @GetMapping("/getOneUser")
    @Operation(summary = "随机获取一个用户")
    public User getOneUser() {
        return new User("姓名", "13899999999");
    }
}

  1. 通过@Schema给自定义对象(入参和返回相同)添加文档注释
@Data
@AllArgsConstructor
@Schema(description = "用户信息")
public class User {

    @Schema(description = "姓名")
    private String name;

    @Schema(description = "电话")
    private String phone;
}

  1. 访问地址:http://localhost:8888/swagger-ui/index.html

到此一个简单的接口文档便生成了,下面是效果图:
在这里插入图片描述
实体注释:
在这里插入图片描述

如上就是open api3的全部设置,它是基于swagger-ui设计的,因此界面和swagger没什么区别。

不过open api3的注解与swagger2完全不同,下面是两者注解的对应关系,方便swagger2的使用者快速开发。




open api与swagger注解方法的对应关系

open api的注解与swagger的有很大区别,open api的写法更为简单易懂,在实际使用时也不会像swagger的注解那样让人迷惑。


如下是两者注解的对应关系:
在这里插入图片描述
官网链接: 官网链接


下面介绍一款swagger的增强框架—knife4j,它的界面美观性因人而异,但是在使用体验上绝对甩swagger界面好多倍。废话不多说,直接将knife4j撸进来。





集成knife4j

官网文档: Knife4j

  1. 依赖导入
<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>knife4j-springdoc-ui</artifactId>
	<version>3.0.3</version>
</dependency>

ok,配置好之后,直接访问Knife4j的界面试试:http://localhost:8888/doc.html

Swagger和Knife4j的访问地址不同,但是都可以修改。

  • http://localhost:8888/swagger-ui/index.html
  • http://localhost:8888/doc.html

在这里插入图片描述
这时,Knife4j的访问界面都是一片空白的,不过不用慌,因为我们还需要为Knife4j添加相应的文件目录


  1. 在此前为的配置文件OpenApiConfig中,添加Knife4j的文档设置,这里所有前缀为“PRIVATE_PATH”的接口,都用过“基础接口”这个目录来访问
@Bean
public GroupedOpenApi publicApi() {
    return GroupedOpenApi.builder()
            .group("基础接口")
            .pathsToMatch(PRIVATE_PATH + "/**")
            .build();
}

此时重启,Knife4j的页面内容如下:
在这里插入图片描述
在这里插入图片描述


  1. 相关功能点介绍
  • 主页:展示了一些接口的统计信息
  • SwaggerModels:展示了所有的传输对象
  • 文档管理:提供全局参数设置(如在请求头添加token登)、离线文档下载(Knife4j提供导出4种格式的离线文档(Html/Markdown/Word/OpenAPI))、以及一些其它个性化设置。
  • 用户接口”:这些目录就是我们生成好的接口文档了。





API文档的常用内容

为@PathVariable的参数添加文档注释

添加@Parameter参数就行

    @GetMapping("/getName/{userName}")
    @Operation(summary = "获取用户名")
    public String getName(@Parameter(required = true, name = "userName", description = "用户名")
                                 @PathVariable("userName") String userName) {
        return userName;
    }

在这里插入图片描述



接口分组

接口分组的方式很简单,即在文件中设置其它分组,同时设置不同的请求路径即可

    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("公共接口")
                .pathsToMatch(PUBLIC_PATH + "/**")
                .build();
    }
    @Bean
    public GroupedOpenApi privateApi() {
        return GroupedOpenApi.builder()
                .group("私有接口")
                .pathsToMatch(PRIVATE_PATH + "/**")
                .build();
    }



设置全局请求头(token)

如果需要为某个分组添加必填字段的话,可以通过如下方式实现:

    @Bean
    public GroupedOpenApi tokenApi(OperationCustomizer operationCustomizer) {
        return GroupedOpenApi.builder()
                .group("鉴权")
                .pathsToMatch(PRIVATE_PATH + "/**")
                .addOperationCustomizer(operationCustomizer)
                .build();
    }

    @Bean
    public OperationCustomizer operationCustomizer() {
        return (operation, handlerMethod) -> operation.addParametersItem(
                new Parameter()
                        .in("header")
                        .required(true)
                        .description("token 验证")
                        .name("token"));
    }

此时该分组的接口,必须传递该字段(当然这只是一种规范,实际请求时还需要自行加上token登必传字段的校验)
在这里插入图片描述

在使用文档时,可以在全局参数设置中添加改参数,避免每个接口都要再填一遍(确定后刷新生效)。
在这里插入图片描述



在特定环境屏蔽API文档

开发和测试环境需要文档,但是上线之后,就必须把这些文档给屏蔽调。

比如生成环境prod,只需要在生成环境的yml文件中需改如下springdoc的配置即可:

springdoc:
  packages-to-scan: com.example.swagger3knife4j.controller
  swagger-ui:
    enabled: false
  api-docs:
    enabled: false





源码地址

源码: github仓库地址

评论 1
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值