Ballcat

Appearance

OpenAPI 文档 (Swagger) ​

什么是 OpenAPI ​

首先 OpenAPI 其实就是 Swagger, Swagger 规范于 2015 年 更名为 OpenAPI 规范，简称 OAS.

OpenAPI 规范的变更时间:

版本日期笔记
3.0.32020-02-20OpenAPI 规范 3.0.3 补丁发布
3.0.22018-10-08OpenAPI 规范 3.0.2 补丁发布
3.0.12017-12-06OpenAPI 规范 3.0.1 补丁发布
3.0.02017-07-26OpenAPI 规范 3.0.0 的发布
3.0.0-rc22017-06-163.0 规范的 rc2
3.0.0-rc12017-04-273.0 规范的 rc1
3.0.0-rc02017-02-283.0 规范的实施者草案
2.02015-12-31将 Swagger 2.0 捐赠给 OpenAPI Initiative
2.02014-09-08Swagger 2.0 发布
1.22014-03-14正式文件的初始发布。
1.12012-08-22Swagger 1.1 发布
1.02011-08-10Swagger 规范的首次发布

可以看到，3.0.0 发布距今 2021 年，已有 4 年之久了，是时候抛弃 Swagger2 切换到 OpenApi3 了。

升级 Swagger2 到 OpenApi3，可以参看此 文档

使用方式 ​

由于 springfox 社区已经超过一年半的时间没有进行更新维护了，所以推荐大家使用 springdoc-openapi 来构建 swagger 文档。

springdoc 官方文档地址：https://springdoc.org，这里摘录并翻译部分，更多使用可参看原文档。

依赖引入 ​

引入 ui 依赖后，在 springboot 环境下，直接启动即可，无需任何额外配置

  • spring-webmvc 环境下引入

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

  • spring-webflux 环境下引入

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

这将自动将 swagger-ui 部署到 spring-boot 应用程序：

  • 文档将以 HTML 格式提供，使用官方 swagger-ui jars
  • 启动项目后，访问 http://server:port/context-path/swagger-ui.html 即可进入 Swagger UI 页面，OpenAPI 描述将在以下 json 格式的 url 中 提供：http://server:port/context-path/v3/api-docs
    • server：域名 或 IP
    • port：服务器端口
    • context-path：应用程序的上下文路径，springboot 默认为空
  • 文档也可以 yaml 格式提供，位于以下路径：/v3/api-docs.yaml

替换 UI ​

如果嫌弃官方提供的 swagger-ui 不美观，或者使用不顺手，可以选择关闭 ui，还可以剔除掉 ui 相关的 webjar 的引入。

yaml
springdoc:
  swagger-ui:
    enabled: false

OpenAPI 文档信息，默认可在此 url 中获取： http://server:port/context-path/v3/api-docs。
可以利用其他支持 OpenAPI 协议的工具，通过此地址，进行 API 展示，如 Apifox。
（ Postman 的 api 测试也可以利用此地址进行导入生成 ）

Knife4j (原 swagger-bootstrap-ui) 3.x 版本提供了对于 OpenAPI 协议的部分支持。

警告

Knife4j 很多地方没有按照协议规范实现，所以使用起来会有很多问题，另外项目也很久没有维护了，不推荐使用。

xml
    <!-- swagger 增强版 ui -->
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-springdoc-ui</artifactId>
        <version>3.0.3</version>
    </dependency>

注意，这里一定要引入 v3.0.3 或以上版本，目前最高 v3.0.3

由于 knife4j 对于规范支持的不全面，无法直接使用单文档源数据，所以必须进行分组或者 urls 的指定。

yaml
# urls
springdoc:
  swagger-ui:
    urls:
      - { name: 'sample', url: '/v3/api-docs' }

或者

yaml
#分组
springdoc:
  group-configs:
    - { group: 'sample', packages-to-scan: 'com.example' }

更多分组或者 urls 配置，请看文档聚合和分组一节。

Knife4j 的 UI 访问地址有所不同，页面映射在 doc.html 路径下，启动项目后，访问 http://server:port/context-path/doc.html

即可进入 Knife4j 的 Swagger UI 页面。

Javadoc 支持 ​

springdoc-openapi 目前支持将 javadoc 转换为 swagger 信息来源的能力，而无需用户在项目中添加对应的 Swagger 的注解。

对于想要启用 javadoc 支持的项目，在之前的依赖之外，还需要额外添加以下依赖：

xml
   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-javadoc</artifactId>
      <version></version> 
   </dependency>

此依赖项改进了对 javadoc 标记和注释的支持：

  • 方法的 javadoc 注释：解析为 @Operation 描述
  • @return : 解析为 @Operation 响应描述
  • 属性的 javadoc 注释：被解析为此字段的 @Schema 描述。

javadoc 支持基于 therapi-runtime-javadoc，所以需要开启了对应的注解处理器，否则不会生效

在 maven-compiler-plugin 添加对应的注解处理器

xml
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <annotationProcessorPaths>
                        <path>
                            <groupId>com.github.therapi</groupId>
                            <artifactId>therapi-runtime-javadoc-scribe</artifactId>
                            <version>0.12.0</version>
                        </path>
                    </annotationProcessorPaths>
                </configuration>
            </plugin>
        </plugins>
    </build>

如果同时存在 swagger-annotation 描述和 javadoc 注释。将使用 swagger-annotation 描述的值。

定制 OpenApi 基本信息 ​

springdoc 默认只支持使用使用注解，或者注册 SpringBean 的形式构建 openApi，由于之前习惯了在 yaml 中定义这些信息，所以 ballcat 对此进行了部分封装，同时支持 cors 跨域配置，方便做文档聚合。

依赖引入：

xml
  <dependency>
      <groupId>org.ballcat</groupId>
      <artifactId>ballcat-spring-boot-starter-openapi</artifactId>
      <version>2.0.0-SNAPSHOT</version>
  </dependency>

配置示例：

yaml
ballcat:
  openapi:
    info:
      title: BallCat-Admin Docs 
      description: BallCat 后台管理服务Api文档
      version: ${project.version}
      terms-of-service: http://www.ballcat.cn/
      license:
        name: Powered By BallCat
        url: http://www.ballcat.cn/
      contact:
        name: Hccake
        email: [email protected]
        url: https://github.com/Hccake
    components:
      # 鉴权方式配置
      security-schemes:
        apiKey:
          type: APIKEY
          in: HEADER
          name: 'api-key'
        oauth2:
          type: OAUTH2
          flows:
            password:
              token-url: http://ballcat-admin:8089/oauth/token
    # 全局默认的鉴权方式支持
    security:
      - oauth2: []
      - apiKey: []

属性配置 ​

ballcat-extend-openapi 属性 ​

参数名称默认值描述
ballcat.openapi.enabledtrueBoolean, 用于开启或关闭 OpenApi 文档
ballcat.openapi.info.titleString. OpenApi 标题
ballcat.openapi.info.descriptionString. OpenApi 描述
ballcat.openapi.info.terms-of-serviceString. OpenApi 服务条款URL
ballcat.openapi.info.versionString. OpenApi 文档版本
ballcat.openapi.info.contact.nameString. OpenApi 联系人名称
ballcat.openapi.info.contact.urlString. OpenApi 联系 URL 地址
ballcat.openapi.info.contact.emailString. OpenApi 联系邮箱
ballcat.openapi.info.license.nameString. 许可证名称
ballcat.openapi.info.license.urlString. 许可证 url
ballcat.openapi.external-docs.descriptionString. 扩展文档描述
ballcat.openapi.external-docs.urlString. 扩展文档链接
ballcat.openapi.components.security-schemes.*Map. 安全配置的map，key 为 String 类型，value 为 SecurityScheme 类型，其属性太多，这里不展开了，具体可参看 open api 官方文档 securitySchemeObject
ballcat.openapi.global-security-requirements.*Map. 全局默认的安全配置，key 对应刚才配置的 SecurityScheme , value 为 list 类型，用来存放安全配置需要的 scope，除了 oauth2 和 openIdConnect 类型的安全配置，其余都是空数组，参看官方文档
ballcat.openapi.cors-config.enabledfalseBoolean, 用于开启或关闭 CORS 跨域配置，默认不开启
ballcat.openapi.cors-config.url-pattern/**String. 跨域对应的 url 匹配规则，为了方便调试，默认为全局
ballcat.openapi.cors-config.allowed-originsList of Strings.允许跨域的源
ballcat.openapi.cors-config.allowed-origin-patternsList of Strings.允许跨域来源的匹配规则
ballcat.openapi.cors-config.allowed-methods["*"]List of Strings.允许跨域的方法列表
ballcat.openapi.cors-config.allowed-headers["*"]List of Strings.允许跨域的头信息
ballcat.openapi.cors-config.exposed-headers["traceId"]List of Strings. 额外允许跨域请求方获取的 response header 信息
ballcat.openapi.cors-config.allow-credentialstrueBoolean, 是否允许跨域发送 Cookie
ballcat.openapi.cors-config.max-ageNumber. CORS 配置缓存时间

springdoc-openapi 属性 ​

参数名称默认值描述
springdoc.api-docs.path/v3/api-docsString, 用于自定义 Json 格式的 OpenAPI 文档路径。
springdoc.api-docs.enabledtrueBoolean. 禁用 springdoc-openapi 端点（默认为 /v3/api-docs）。
springdoc.packages-to-scan*List of Strings.要扫描的包列表（逗号分隔）
springdoc.paths-to-match/*List of Strings.要匹配的路径列表（逗号分隔）
springdoc.produces-to-match/*List of Strings.要匹配的生产媒体类型列表（逗号分隔）
springdoc.headers-to-match/*List of Strings.要匹配的标题列表（逗号分隔）
springdoc.consumes-to-match/*List of Strings.要匹配的消耗媒体类型列表（逗号分隔）
springdoc.paths-to-excludeList of Strings.要排除的路径列表（逗号分隔）
springdoc.packages-to-excludeList of Strings.要排除的包列表（逗号分隔）
springdoc.default-consumes-media-typeapplication/jsonString. 默认使用媒体类型。
springdoc.default-produces-media-type**/**String.默认产生媒体类型。
springdoc.cache.disabledfalseBoolean. 禁用计算出来的 OpenAPI 的 springdoc-openapi 缓存。
springdoc.show-actuatorfalseBoolean. 显示执行器端点。
springdoc.auto-tag-classestrueBoolean. 禁用 springdoc-openapi 自动标签。
springdoc.model-and-view-allowedfalseBoolean. 允许带有 ModelAndView 的 RestControllers 返回出现在 OpenAPI 描述中。
springdoc.override-with-generic-responsetrueBoolean. 当为 true 时，自动将 @ControllerAdvice 响应添加到所有生成的响应中。
springdoc.api-docs.groups.enabledtrueBoolean. 禁用 springdoc-openapi 组。
springdoc.group-configs[0].groupString.文档分组标识
springdoc.group-configs[0].display-nameString.文档分组的显示名称.
springdoc.group-configs[0].packages-to-scan*List of Strings.要扫描的包列表（逗号分隔）
springdoc.group-configs[0].paths-to-match/*List of Strings. 匹配组的路径列表（逗号分隔）
springdoc.group-configs[0].paths-to-excludeList of Strings.要排除的路径列表（逗号分隔）
springdoc.group-configs[0].packages-to-excludeList of Strings.要排除的包列表（逗号分隔）
springdoc.group-configs[0].produces-to-match/*List of Strings.要匹配的生产媒体类型列表（逗号分隔）
springdoc.group-configs[0].consumes-to-match/*List of Strings.要匹配的消耗媒体类型列表（逗号分隔）
springdoc.group-configs[0].headers-to-match/*List of Strings.要匹配的标题列表（逗号分隔）
springdoc.webjars.prefix/webjarsString, 要更改可见的 webjars 前缀，请更改 spring-webflux 的 swagger-ui 的 URL。
springdoc.api-docs.resolve-schema-propertiesfalseBoolean. 在@Schema 上启用属性解析器（名称、标题和描述）。
springdoc.remove-broken-reference-definitionstrueBoolean. 禁止删除损坏的参考定义。
springdoc.writer-with-default-pretty-printerfalseBoolean. 启用 OpenApi 规范的漂亮打印。
springdoc.model-converters.deprecating-converter.enabledtrueBoolean. 禁用弃用模型转换器。
springdoc.model-converters.polymorphic-converter.enabledtrueBoolean. 禁用多态模型转换器。
springdoc.model-converters.pageable-converter.enabledtrueBoolean. 禁用可分页模型转换器。
springdoc.use-fqnfalseBoolean. 启用完全限定名称。
springdoc.show-login-endpointfalseBoolean. 使 spring 安全登录端点可见。
springdoc.pre-loading-enabledfalseBoolean. 在应用程序启动时加载 OpenAPI 的预加载设置。
springdoc.writer-with-order-by-keysfalseBoolean. 启用确定性/字母顺序。
springdoc.use-management-portfalseBoolean. 在执行器管理端口上公开 swagger-ui。
springdoc.disable-i18nfalseBoolean. 使用 i18n 禁用自动翻译。
springdoc.show-spring-cloud-functionstrueBoolean. 是否显示 spring-cloud-function 的 web 端点.

swagger-ui 属性 ​

参数名称默认值描述
springdoc.swagger-ui.path/swagger-ui.htmlString, 用于 swagger-ui HTML 文档的自定义路径。
springdoc.swagger-ui.enabledtrueBoolean. 禁用 swagger-ui 端点（默认为 /swagger-ui.html）。
springdoc.swagger-ui.configUrl/v3/api-docs/swagger-configString. 从中获取外部配置文档的 URL。
springdoc.swagger-ui.layoutBaseLayoutString. 可通过插件系统用作 Swagger UI 的顶级布局的组件的名称。
springdoc.swagger-ui.validatorUrlnull默认情况下，Swagger UI 尝试根据 swagger.io 的在线验证器验证规范。您可以使用此参数来设置不同的验证器 URL，例如为本地部署的验证器Validator Badge。将其设置为null将禁用验证。
springdoc.swagger-ui.tryItOutEnabledfalseBoolean. 控制是否应默认启用“试用”部分。
springdoc.swagger-ui.filterfalseBoolean OR String. 如果设置，则启用过滤。顶部栏将显示一个编辑框，您可以使用它来过滤显示的标记操作。可以是布尔值以启用或禁用，也可以是字符串，在这种情况下，将使用该字符串作为过滤器表达式来启用过滤。过滤区分大小写，匹配标签内任何地方的过滤器表达式。
springdoc.swagger-ui.operationsSorterFunction=(a ⇒ a). 对每个 API 的操作列表应用排序。它可以是“alpha”（按字母数字的路径排序）、“method”（按 HTTP 方法排序）或函数（请参阅 Array.prototype.sort() 以了解排序函数的工作原理）。默认是服务器返回的顺序不变。
springdoc.swagger-ui.tagsSorterFunction=(a ⇒ a). 对每个 API 的标签列表应用排序。它可以是“alpha”（按字母数字路径排序）或函数，请参阅 Array.prototype.sort()以了解如何编写排序函数）。每次通过时，将两个标签名称字符串传递给分拣机。默认是 Swagger UI 确定的顺序。
springdoc.swagger-ui.oauth2RedirectUrl/swagger-ui/oauth2-redirect.htmlString. OAuth 重定向 URL。
springdoc.swagger-ui.displayOperationIdfalseBoolean. 控制操作列表中 operationId 的显示。默认为false。
springdoc.swagger-ui.displayRequestDurationfalseBoolean. 控制“试用”请求的请求持续时间（以毫秒为单位）的显示。
springdoc.swagger-ui.deepLinkingfalseBoolean. 如果设置为true，则启用标签和操作的深层链接。有关详细信息，请参阅 深层链接文档。
springdoc.swagger-ui.defaultModelsExpandDepth1Number. 模型的默认扩展深度（设置为 -1 完全隐藏模型）。
springdoc.swagger-ui.defaultModelExpandDepth1Number. 模型示例部分中模型的默认扩展深度。
springdoc.swagger-ui.defaultModelRenderingString=["example"*, "model"]. 控制首次呈现 API 时模型的显示方式。（用户始终可以通过单击“模型”和“示例值”链接来切换给定模型的渲染。）
springdoc.swagger-ui.docExpansionString=["list"*, "full", "none"]. 控制操作和标签的默认扩展设置。它可以是“list”（仅展开标签）、“full”（展开标签和操作）或“none”（不展开任何内容）。
springdoc.swagger-ui.maxDisplayedTagsNumber. 如果设置，将显示的标记操作数量限制为最多这么多。默认是显示所有操作。
springdoc.swagger-ui.showExtensionsfalseBoolean. 控制“x-操作”、“参数”和“架构”的供应商扩展 ( ) 字段和值的显示。
springdoc.swagger-ui.urlString.要配置，自定义 OpenAPI 文件的路径。如果urls使用将被忽略。
springdoc.swagger-ui.showCommonExtensionsfalseBoolean. 控制参数的扩展（pattern、maxLength、minLength、maximum、minimum）字段和值的显示。
springdoc.swagger-ui.supportedSubmitMethodsArray=["get", "put", "post", "delete", "options", "head", "patch", "trace"]. 启用了“试用”功能的 HTTP 方法列表。空数组禁用所有操作的“试用”。这不会从显示中过滤操作。
springdoc.swagger-ui.queryConfigEnabledfalseBoolean. 自禁用v1.6.0。此参数通过 URL 搜索参数启用（旧版）覆盖配置参数。在启用此功能之前，请参阅安全公告。
springdoc.swagger-ui.oauth. additionalQueryStringParamsString. 添加到authorizationUrl 和tokenUrl 的附加查询参数。
springdoc.swagger-ui.disable-swagger-default-urlfalseBoolean. 禁用 swagger-ui 默认 petstore url。（自 v1.4.1 起可用）。
springdoc.swagger-ui.urls[0].urlURL. swagger 组的 url，由 Topbar 插件使用。URL 在此数组中的所有项目中必须是唯一的，因为它们用作标识符。
springdoc.swagger-ui.urls[0].nameString. Topbar 插件使用的 swagger 组的名称。名称在此数组中的所有项目中必须是唯一的，因为它们用作标识符。
springdoc.swagger-ui.urlsPrimaryNameString. Swagger UI 加载时将显示的 swagger 组的名称。
springdoc.swagger-ui.oauth.clientIdString. 默认客户端 ID。必须是字符串。
springdoc.swagger-ui.oauth.clientSecretString. 默认客户端机密。切勿在您的生产环境中使用此参数。它暴露了关键的安全信息。此功能仅适用于开发/测试环境。
springdoc.swagger-ui.oauth.realmString. 领域查询参数（用于 OAuth 1）添加到 authorizationUrl 和 tokenUrl。
springdoc.swagger-ui.oauth.appNameString. OAuth 应用程序名称，显示在授权弹出窗口中。
springdoc.swagger-ui.oauth.scopeSeparatorString. 用于传递范围的 OAuth 范围分隔符，在调用前编码，默认值为空格（编码值 %20）。
springdoc.swagger-ui.csrf.enabledfalseBoolean. 启用 CSRF 支持
springdoc.swagger-ui.csrf.use-local-storagefalseBoolean. 从 Local Storage 获取 CSRF token。
springdoc.swagger-ui.csrf.use-session-storagefalseBoolean. 从 Session Storage 获取 CSRF token。
springdoc.swagger-ui.csrf.cookie-nameXSRF-TOKENString. 可选 CSRF，设置 CSRF cookie 名称。
springdoc.swagger-ui.csrf.header-nameX-XSRF-TOKENString. 可选的 CSRF，设置 CSRF 头名称。
springdoc.swagger-ui.syntaxHighlight.activatedtrueBoolean. 是否应激活语法突出显示。
springdoc.swagger-ui.syntaxHighlight.themeagateString. String=["agate"*, "arta", "monokai", "nord", "obsidian", "tomorrow-night"]. 要使用的Highlight.js语法着色主题。（仅提供这 6 种样式。）
springdoc.swagger-ui.oauth. useBasicAuthentication WithAccessCodeGrantfalseBoolean. 仅针对 accessCode 流激活。在对 tokenUrl 的 authorization_code 请求期间，使用 HTTP 基本身份验证方案（带有基本 base64encode(client_id + client_secret) 的授权标头）传递客户端密码。
springdoc.swagger-ui.oauth. usePkceWithAuthorization CodeGrantfalseBoolean.仅适用于授权码流。代码交换证明密钥为 OAuth 公共客户端带来了增强的安全性。
springdoc.swagger-ui.persistAuthorizationfalseBoolean. 如果设置为 true，它会保留授权数据，并且不会在浏览器关闭/刷新时丢失
springdoc.swagger-ui.use-root-pathfalseBoolean. 如果设置为 true，则可以直接从应用程序根路径访问 swagger-ui。

文档聚合和分组 ​

文档聚合 ​

当有多个服务提供时，在一个 ui 页面聚合查看所有服务的 API 文档。

这个 UI 页面所属的服务我们称为聚合者 Aggregator，其他的服务则成为文档提供者 Provider。

注意，仅需在文档聚合者的服务中引入 UI 依赖，其他服务可以不引入

由于聚合者和提供者的域名端口等信息可能不一致，则此时会出现跨域问题，所以提供者一般需要允许聚合者的源对其进行跨域访问。

聚合示例 ​

我们以 ballcat-admin 和 ballcat-api 两个服务为例：

当把 ballcat-admin 做为聚合者时，其配置文件中，需要添加 ballcat-api 的文档源地址：

yaml
springdoc:
  swagger-ui:
    urls:
      - { name: 'admin', url: '/v3/api-docs' } #其自身的文档地址，源信息可以省略
      - { name: 'api', url: 'http:///ballcat-api:9090/v3/api-docs' }

而 ballcat-api 则处理跨域问题，允许 ballcat-admin 的跨域访问，在引入了 ballcat-extend-openapi 模块的情况下，可以通过添加如下配置，达到允许跨域的功能：

yaml
ballcat:
  openapi:
    cors-config:
      enabled: true
      allowed-origins:
        - "http://ballcat-admin:8080"

启动两个服务后，访问 swagger-ui 页面，在 UI 的右上角，即可进行文档的切换显示：

openapi-aa

微服务下的聚合 ​

通过自己配置 url-mapping：/swagger-config.json，替换 springdoc 默认提供的 swagger-config:

然后通过服务发现机制，获取到所有的服务示例，将其对应的文档源地址注册并返回出去：

java
@RestController
public class SwaggerUiConfig {

    @Autowired
    private DiscoveryClient discoveryClient;

    @GetMapping("/swagger-config.json")
    public Map<String, Object> swaggerConfig() {
        Map<String, Object> config = new LinkedHashMap<>();
        List<SwaggerUrl> urls = new LinkedList<>();
        discoveryClient.getServices().forEach(serviceName -> 
                        discoveryClient.getInstances(serviceName).forEach(serviceInstance ->
                                urls.add(new SwaggerUrl(serviceName, serviceInstance.getUri() + "/v3/api-docs"))
                        )
        );
        config.put("urls", urls);
        return config;
    }
}

更多详情，可参看官方 issue: Centralized API Documentation

文档分组 ​

不同于文档聚合，文档分组是在一个服务内部，根据一定的规则，将自身提供的 API 进行分组管理

以 ballcat-admin 为例，我们可以根据包名，将其文档拆分成 sample 和 ballcat 两个分组

刚才的 springdoc.swagger-ui.urls 属性就不需要配置了

yaml
springdoc:
  group-configs:
    - {group: 'sample', packages-to-scan: 'com.your'}
    - {group: 'ballcat', packages-to-scan: 'org.ballcat.ballcat'}

openapi-group

除了根据包名外，还可以根据 path 等其他信息，具体参看刚才的属性配置一节，这里不再过多演示。

搭配使用聚合和分组 ​

我们将 ballcat-admin 拆分成两个分组 sample 和 ballcat

将 ballcat-api 也拆分成两个分组 api-user 和 api-test

则 ballcat-api 的配置文件如下：

yaml
ballcat:
  openapi:
    cors-config:
      enabled: true # 跨域支持
      allowed-origins: 
        - "http://ballcat-admin:8080"

springdoc:
  group-configs: # 这里根据 path，请求路径进行分组
    - {group: 'api-user', paths-to-match: '/user/**'}
    - {group: 'api-test', paths-to-match: '/public/**'}

f分组的文档地址规则为：http://server:port/context-path/v3/api-docs/groupName

所以 api-user 分组的文档源地址将会变为：http://ballcat-api:9090/v3/api-docs/api-user

而 ballcat-admin 的配置文件如下：

yaml
springdoc:
  group-configs:
    - {group: 'sample', packages-to-scan: 'com.your'}
    - {group: 'ballcat', packages-to-scan: 'org.ballcat.ballcat'}
  swagger-ui:
    urls:
      - { name: 'api-user', url: 'http://ballcat-api:9090/v3/api-docs/api-user' }
      - { name: 'api-test', url: 'http://ballcat-api:9090/v3/api-docs/api-test' }

注意：当聚合者自身进行分组时，urls 属性中，不必在配置其自身文档源地址

openapi-aggregator-group

安全方案 ​

安全方案类型 ​

OpenAPI 规范中支持的安全方案是

  • HTTP 身份验证
  • API key （作为 Header 或 查询参数）
  • OAuth2 的通用流程（implicit, password, application and access code），如RFC6749
  • OpenID Connect Discovery

在 java 中的抽象类型对应 io.swagger.v3.oas.models.security.SecurityScheme：

这里摘录官方文档中的部分介绍：

字段名称类型适用于描述
typestringAny必须的. 安全方案的类型。有效值为 "apiKey", "http", "oauth2", "openIdConnect".
descriptionstringAny安全方案的简短描述。
namestringapiKey必须的. API key 在 header, query or cookie 的参数名称
instringapiKey必须的. API key 在请求中的位置. 有效值为"query","header"或"cookie"。
schemestringhttp必须的. 要在 RFC7235 中定义的Authorization 标头中使用的 HTTP 授权方案的名称。
bearerFormatstringhttp ("bearer")提示客户端识别不记名令牌的格式。不记名令牌通常由授权服务器生成，因此此信息主要用于文档目的。
flowsOAuth Flows Objectoauth2必须的. 一个 包含了支持的 OAuth2 流类型的配置信息的对象
openIdConnectUrlstringopenIdConnect必须的. 提供 OAuth2 配置的 OpenId Connect URL.

更多信息参看：https://github.com/OAI/OpenAPI-Specification/blob/3.0.1/versions/3.0.1.md#security-scheme-object

配置 ApiKey 安全方案 ​

springdoc 默认是通过注册 OpenApi 类型的 bean，并在其中设置相关的安全方案配置。

具体可以参看其示例：springdoc-openapi-demos

在引入了 ballcat-extend-openapi 依赖时，可以通过 yaml 配置的方式进行定义：

yaml
ballcat:
  openapi:
  	info:
      title: BallCat-Admin Docs
      version: ${project.version}
    components:
      security-schemes:
        apiKey:
          type: APIKEY
          in: HEADER  # 表示在请求头中携带参数
          name: 'api-key' # 表示请求头的名称为 api-key
        oauth2:
          type: OAUTH2 
          flows:
            password: # OAuth2 密码模式
              token-url: http://ballcat-admin:8080/oauth/token
    # 全局接口都默认使用 oauth2 和 apiKey 两种鉴权方式
    security:
      - oauth2: []
      - apiKey: []

启动后会发现，多了一个授权按钮：

openapi-authorize

点击按钮后，可以在弹窗中输入一个已被授权的 ApiKey，这里我们填入 wo-de-api-key

openapi-apikey

然后单击 Authorize 按钮，即可授权成功

openapi-apikey

之后，我们随便找一个接口进行 Try it out 调试，点击 execete 后，返现 swagger-ui 在向后台接口发起访问时，会自动将我们填写的 ApiKey 附着在请求头上

openapi-apikey-header

接口独立配置安全方案 ​

可以在接口上添加 @SecurityRequirement 注解， 以表示当前接口走指定的安全方案，从而覆盖全局的安全方案配置

java
@SecurityRequirement(name = "ballcat-oauth")

以上注解被添加到接口上后表示，该接口使用一个 name 为 ballcat-oauth 的安全方案

接口忽略安全方案 ​

如果有接口时对外抛出，无需鉴权处理的，可以通过添加一个空的 @SecurityRequirements 注解，标识其无需鉴权

java
@SecurityRequirements