一、什么是springdoc-openapi

Springdoc-openapi 是一个用于生成 OpenAPI（之前称为 Swagger）文档的库，专为 Spring Boot 应用程序设计。它可以根据你的 Spring MVC 控制器、REST 控制器和其他 Spring Bean 自动生成 OpenAPI 文档，从而帮助你在开发 RESTful API 时更加高效地管理和维护 API 文档。Springdoc-openapi 支持 OpenAPI 3.x 版本，并提供了一些额外的功能，如自定义配置、注解支持和与 Spring Boot 的无缝集成。

当你构建 RESTful API 时，API 文档是非常重要的，因为它们提供了对 API 的清晰描述，包括可用端点、请求参数、响应模型等信息。Springdoc-openapi 就是为了简化生成这些 API 文档而设计的。

Springdoc-openapi 的主要功能包括：

1. 自动生成文档： Springdoc-openapi 可以自动扫描你的 Spring Boot 应用程序，并根据其中的控制器和其他相关组件生成 OpenAPI 文档。你无需手动编写文档，大部分信息都是自动生成的。

2. 支持 OpenAPI 3.x： Springdoc-openapi 支持 OpenAPI 3.x 版本规范，这是当前 RESTful API 开发的主流规范。

3. 注解支持： 它与 Spring MVC 注解和其他常见的 Spring 注解完全兼容，你可以使用这些注解来定制 API 的文档信息，例如请求参数的描述、响应的格式等。

4. 自定义配置： Springdoc-openapi 提供了丰富的配置选项，你可以根据项目的需求进行自定义配置，以满足特定的文档生成需求。

5. 集成简便： 由于 Springdoc-openapi 是专为 Spring Boot 应用程序设计的，因此它与 Spring Boot 无缝集成。你只需将 Springdoc-openapi 添加到项目的依赖中，它就会自动集成到你的应用程序中，开始生成 API 文档。

springdoc-openapi 使得生成和维护 RESTful API 文档变得简单而高效，帮助开发人员专注于业务逻辑而不是文档的编写。

核心注解

以下是 Springdoc-openapi 中一些常用的核心注解及其描述：

这些注解可以帮助开发者更精细地描述 API 的各个方面，从而生成更加详细和准确的 OpenAPI 文档。

从 Swagger 2 升级为 Swagger 3

下面是将 Swagger 2 注解替换为 Swagger 3 注解的翻译：

• @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”)

  这些转换可以帮助将现有的 Swagger 2 注解替换为 Swagger 3 注解，以便与 Springdoc-openapi-starter-webmvc-ui 库一起使用。

  二、什么是Knife4j

  Knife4j 是一个基于 Swagger 实现的接口文档管理工具，它提供了一套简单易用的 UI 界面，用于展示和管理 Swagger 生成的 API 文档。与传统的 Swagger UI 相比，Knife4j 在 UI 设计和功能上进行了改进和增强，使得接口文档的浏览和管理更加方便和直观。

  Knife4j 的特点和功能包括：

  1. 美观的界面设计： Knife4j 提供了一个美观、直观的界面，用户可以通过该界面轻松地浏览和理解 API 文档，以及进行相关操作。

  2. 增强的交互功能： Knife4j 在 Swagger UI 的基础上增加了一些交互功能，如请求参数的快速填充、响应结果的格式化显示等，提升了用户体验。

  3. 便捷的文档导航： Knife4j 提供了便捷的文档导航功能，用户可以通过目录结构快速定位到所需的接口文档，方便查阅和使用。

  4. 支持在线调试： Knife4j 允许用户在界面上直接进行接口调用和测试，无需额外的工具或插件，便可完成接口的调试和验证。

  5. 自动生成文档： Knife4j 可以直接集成到 Spring Boot 项目中，通过注解和配置自动生成接口文档，简化了文档编写的工作量。

  总的来说，Knife4j 是一个功能强大、易用的接口文档管理工具，能够帮助开发者更加高效地管理和维护 API 文档，提升接口开发和调试的效率。

  主要配置项

  在以前的版本中,开发者需要在配置文件中手动使用@EnableKnife4j来使用增强，自2.0.6版本后,只需要在配置文件中配置knife4j.enable=true即可不在使用注解

  注意：要使用Knife4j提供的增强，knife4j.enable=true必须开启

  各个配置属性说明如下：

  属性	默认值	说明值
  knife4j.enable	false	是否开启Knife4j增强模式
  knife4j.cors	false	是否开启一个默认的跨域配置,该功能配合自定义Host使用
  knife4j.production	false	是否开启生产环境保护策略
  knife4j.basic		对Knife4j提供的资源提供BasicHttp校验,保护文档
  knife4j.basic.enable	false	关闭BasicHttp功能
  knife4j.basic.username		basic用户名
  knife4j.basic.password		basic密码
  knife4j.documents		自定义文档集合，该属性是数组
  knife4j.documents.group		所属分组
  knife4j.documents.name		类似于接口中的tag,对于自定义文档的分组
  knife4j.documents.locations		markdown文件路径,可以是一个文件夹(classpath:markdowns/*)，也可以是单个文件(classpath:md/sign.md)
  knife4j.setting		前端Ui的个性化配置属性
  knife4j.setting.enable-after-script	true	调试Tab是否显示AfterScript功能,默认开启
  knife4j.setting.language	zh-CN	Ui默认显示语言,目前主要有两种:中文(zh-CN)、英文(en-US)
  knife4j.setting.enable-swagger-models	true	是否显示界面中SwaggerModel功能
  knife4j.setting.swagger-model-name	Swagger Models	重命名SwaggerModel名称,默认
  knife4j.setting.enable-document-manage	true	是否显示界面中"文档管理"功能
  knife4j.setting.enable-reload-cache-parameter	false	是否在每个Debug调试栏后显示刷新变量按钮,默认不显示
  knife4j.setting.enable-version	false	是否开启界面中对某接口的版本控制,如果开启，后端变化后Ui界面会存在小蓝点
  knife4j.setting.enable-request-cache	true	是否开启请求参数缓存
  knife4j.setting.enable-filter-multipart-apis	false	针对RequestMapping的接口请求类型,在不指定参数类型的情况下,如果不过滤,默认会显示7个类型的接口地址参数,如果开启此配置,默认展示一个Post类型的接口地址
  knife4j.setting.enable-filter-multipart-api-method-type	POST	具体接口的过滤类型
  knife4j.setting.enable-host	false	是否启用Host
  knife4j.setting.enable-host-text	false	HOST地址
  knife4j.setting.enable-home-custom	false	是否开启自定义主页内容
  knife4j.setting.home-custom-path		主页内容Markdown文件路径
  knife4j.setting.enable-search	false	是否禁用Ui界面中的搜索框
  knife4j.setting.enable-footer	true	是否显示Footer
  knife4j.setting.enable-footer-custom	false	是否开启自定义Footer
  knife4j.setting.footer-custom-content	false	自定义Footer内容
  knife4j.setting.enable-dynamic-parameter	false	是否开启动态参数调试功能
  knife4j.setting.enable-debug	true	启用调试
  knife4j.setting.enable-open-api	true	显示OpenAPI规范
  knife4j.setting.enable-group	true	显示服务分组

  三、SpringBoot3.0 集成 Knife4j 步骤

  1、添加依赖（3.0和2.0不一样）

  
  	com.github.xiaoymin
  	knife4j-openapi3-jakarta-spring-boot-starter
  	4.4.0
  
  

  • Spring Boot 3 只支持OpenAPI3规范
  • Knife4j提供的starter已经引用springdoc-openapi的jar，开发者需注意避免jar包冲突
  • JDK版本必须 >= 17

  2、在 application.yml 中添加配置

  springdoc:
    swagger-ui:
      tags-sorter: alpha
    group-configs:
      - group: bis
        display-name: "业务接口文档"
        paths-to-match: '/**'
        packages-to-scan: org.shi9.module.bis
      - group: system
        display-name: "系统接口文档"
        paths-to-match: '/**'
        packages-to-scan: org.shi9.module.system
    default-flat-param-object: true
  knife4j:
    # 开启增强配置
    enable: true
    # 开启生产环境屏蔽（如果是生产环境，需要把下面配置设置true）
  #  production: true
    setting:
      language: zh_cn
      swagger-model-name: 实体类列表
    basic: # 开始授权认证
      enable: true
      username: admin
      password: 123456
  

  在 group-configs 下面配置不同的模块的接口分组，也可以通过代码配置，建议在yml中配置。代码配置类似如下：

  @Bean
  public GroupedOpenApi publicApi() {
      return GroupedOpenApi.builder()
              .group("springshop-public")
              .pathsToMatch("/public/**")
              .build();
  }
  @Bean
  public GroupedOpenApi adminApi() {
      return GroupedOpenApi.builder()
              .group("springshop-admin")
              .pathsToMatch("/admin/**")
              .addOpenApiMethodFilter(method -> method.isAnnotationPresent(Admin.class))
              .build();
  }
  

  3、增加配置类 SwaggerConfig.java

  import io.swagger.v3.oas.models.Components;
  import io.swagger.v3.oas.models.OpenAPI;
  import io.swagger.v3.oas.models.info.Contact;
  import io.swagger.v3.oas.models.info.Info;
  import io.swagger.v3.oas.models.info.License;
  import io.swagger.v3.oas.models.security.SecurityScheme;
  import org.shi9.common.constant.CommonConstant;
  import org.springframework.context.annotation.Bean;
  import org.springframework.context.annotation.Configuration;
  @Configuration
  public class SwaggerConfig {
      @Bean
      public OpenAPI customOpenAPI() {
          Contact contact = new Contact();
          contact.setEmail("wlddhj@163.com");
          contact.setName("huangjian");
          contact.setUrl("http://doc.xiaominfo.com");
          return new OpenAPI()
                  // 增加swagger授权请求头配置
                  .components(new Components().addSecuritySchemes(CommonConstant.X_ACCESS_TOKEN,
                          new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme(CommonConstant.X_ACCESS_TOKEN)))
                  .info(new Info()
                          .title("Shi9 后台服务API接口文档")
                          .version("1.0")
                          .contact(contact)
                          .description("Knife4j集成springdoc-openapi示例")
                          .termsOfService("http://doc.xiaominfo.com")
                          .license(new License().name("Apache 2.0")
                                  .url("http://www.apache.org/licenses/LICENSE-2.0.html")));
      }
  }
  

  4、启动项目

  项目启动后，直接打开地址 http://localhost:8081/doc.html，可以看见类型如下页面

  

  参考

  • https://doc.xiaominfo.com/docs/quick-start
  • https://springdoc.org/#getting-started
  • https://springdoc.org/
  • https://gitee.com/xiaoym/knife4j
   
   企业网站建设目的有哪些  专门制作网页的软件  宿迁网站建设  濮阳网  免费姓名logo设计  如何做一个企业的网站