OpenAPI 与 springdoc

服务的路由来自它的 Manifest，它们的 OpenAPI 文档也是：每个命令、状态读取、查询和数据集路由，以及 Manifest 中类型的请求和响应 schema。本页说明在哪里获取这份文档，以及它怎样并入 springdoc 的文档。

获取文档

在哪里	何时
GET /wow/openapi	运行时，从服务合并后的 Manifest 生成（wow.http.openapi.enabled，默认打开）
build/wow/openapi.json	构建时，由 Gradle 插件的 generateWowOpenApi 生成，供需要在服务运行之前就拿到它的工具使用

文档是 OpenAPI 3.1，使用 JSON Schema 2020-12 的 schema。它不声明 jsonSchemaDialect：OpenAPI 3.1 的默认方言就是 JSON Schema 2020-12 再加上 OpenAPI 自己的关键字，schema 在它之下含义不变，而 Swagger UI 不接受其他方言。它只描述公开端口：内部端口的调用、集群通道和信号从不出现在其中；公开端口不提供的内部命令（@InternalCommand）及只有它们用到的 schema 也不在其中（只在内部受理的命令）。

配合 springdoc

应用的类路径上有 springdoc 时，Wow 的文档会并入 springdoc 的文档，所以 /v3/api-docs 和 Swagger UI 会同时列出应用自己的控制器和 Wow 的路由：

• Wow 的路由合并进 springdoc 的默认文档。两者都定义了的路由（按路径和方法），或者两者以不同定义使用的同一个组件名，会让启动失败；启动时会渲染一次文档来检查。
• 分组 wow.http.openapi.springdoc.group（wow）单独提供 Wow 的路由，位于 /v3/api-docs/wow。
• Swagger UI 先列出默认文档，再列出各个分组。
• /v3/api-docs 和 Swagger UI 属于 springdoc，由应用的安全配置保护。GET /wow/openapi 不变。

wow.http.openapi.springdoc.enabled: false 关闭这个桥接。

安全方案

springdoc 的文档（/v3/api-docs、/v3/api-docs/wow）声明调用方怎样出示它的身份，这样 Swagger UI 的 “Try it out” 就会发送它；GET /wow/openapi 和构建产出的文档不声明。宿主根据它的调用方解析器填写这部分：CoSec 的解析器接收 bearer 令牌，开发调用方接收 Wow-* 身份请求头，每个请求头一个方案。它们的全局 security 是一条列出它们全部的要求：它们是同一个身份的各个部分，由请求一起发送，而不是几选一。使用自己的解析器的应用，用一个 WowOpenApiSecurity Bean 声明它的方案，这个 Bean 会替换宿主的。

基于文档的客户端

TypeScript 客户端从 Manifest 而不是 OpenAPI 文档生成，这样它们能保留 OpenAPI 表达不了的东西，例如等待计划和查询字段；与文档一样，它们不含内部命令。OpenAPI 文档服务于其他所有语言和工具。