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

超、凢脫俗 2024-04-06 11:04 7阅读 0赞

#### 目录 ####

*   *  API文档集成与增强
     *   *  集成open api
         *  open api使用方法
         *  open api与swagger注解方法的对应关系
         *  集成knife4j
     *  API文档的常用内容
     *   *  为@PathVariable的参数添加文档注释
         *  接口分组
         *  设置全局请求头（token）
         *  在特定环境屏蔽API文档
     *  源码地址

--------------------

### 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

到此一个简单的接口文档便生成了，下面是效果图：  
![在这里插入图片描述][50f67b7344d94e478e8af822d7c441ee.png]  
实体注释：  
![在这里插入图片描述][9a47d775a03a404aa974335667a8937e.png]

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

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

--------------------

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

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

如下是两者注解的对应关系：  
![在这里插入图片描述][356d61947f044ce2813e82527977a2af.png]  
官网链接: [官网链接][Link 1]

下面介绍一款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

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

1.  在此前为的配置文件**OpenApiConfig**中，添加Knife4j的文档设置，这里所有前缀为“**PRIVATE\_PATH**”的接口，都用过“**基础接口**”这个目录来访问

@Bean
    public GroupedOpenApi publicApi() {
        
        return GroupedOpenApi.builder()
                .group("基础接口")
                .pathsToMatch(PRIVATE_PATH + "/**")
                .build();
    }

此时重启，Knife4j的页面内容如下：  
![在这里插入图片描述][9fdccf1c14324a6099bfe15e8c589506.png]  
![在这里插入图片描述][d9315906fab44a70aa1b7d8c73e17daa.png]

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;
        }

![在这里插入图片描述][0ae93a64f452442ba21b29189eab7580.png]

#### 接口分组 ####

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

@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登必传字段的校验）  
![在这里插入图片描述][5d23c734cbc44b0fab7c8efb953d6e07.png]

在使用文档时，可以在全局参数设置中添加改参数，避免每个接口都要再填一遍（确定后刷新生效）。  
![在这里插入图片描述][a367992cadae46fd946bd1c762ae8690.png]

#### 在特定环境屏蔽API文档 ####

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

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

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

--------------------

### 源码地址 ###

源码: [github仓库地址][github]

[springdoc-openapi]: https://springdoc.org/
[50f67b7344d94e478e8af822d7c441ee.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/7696d3ac22404b6aad52aa8e2f3fca6c.png
[9a47d775a03a404aa974335667a8937e.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/40bc4069f49847b1b7b4c8909f19abc3.png
[356d61947f044ce2813e82527977a2af.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/b5cd4c89bf744dde9999017090734b4f.png
[Link 1]: https://springdoc.org/#migrating-from-springfox
[Knife4j]: https://doc.xiaominfo.com/
[d83efb3dbae24c8b8d2341ffadf6fbfe.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/75fa13a127354fb8b78d42b8e77f105f.png
[9fdccf1c14324a6099bfe15e8c589506.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/dc2bc741981043b482a2655cfdb4b565.png
[d9315906fab44a70aa1b7d8c73e17daa.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/bebaf5b6dbac437fa8e93bac9f6e65ba.png
[0ae93a64f452442ba21b29189eab7580.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/ca74a40b0582404f9bc63f6f59e8cd83.png
[5d23c734cbc44b0fab7c8efb953d6e07.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/30ce00d16442453e9e053791196d81d7.png
[a367992cadae46fd946bd1c762ae8690.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/5d0f1ad4ceff4951845485cd07c52c43.png
[github]: https://github.com/VsLegend/swagger3knife4j