ApiHug Spring API Extension

它暴露什么

it-common-spring-api 负责把 proto 编译产物中的 API 文档和元数据通过 HTTP 暴露出来。它不是靠运行时扫描 Controller 反射生成文档，而是直接读取契约生成的资源文件。

主要端点包括：

OpenAPI 文档：/v3/api-docs
指定版本文档：/v3/api-docs/{version}、/v3/api-docs/{version}.yaml
元数据端点：
- /hope/meta/errors
- /hope/meta/dictionaries
- /hope/meta/authorities
- /hope/meta/versions

/v3/api-docs 是 OpenAPI 3 文档，不是 Swagger 2.0。

配置项

配置前缀是 hope.api，不是旧文档里的 hope.open.api。

配置项	默认值	说明
`hope.api.enable`	`true`	是否启用 OpenAPI 文档端点
`hope.api.path`	`/v3/api-docs`	文档主路径
`hope.api.showMeta`	`true`	是否暴露元数据端点
`hope.api.showActuator`	`false`	是否把 actuator 暴露进 API 视图
`hope.api.project.name`	-	关联的 proto 项目名
`hope.api.project.latest`	`true`	是否默认返回最新版本
`hope.api.mcp.mcpServer`	`openapi-server`	MCP Server 名称
`hope.api.mcp.toolPrefixName`	`""`	MCP 工具名前缀
`hope.api.mcp.serverUrl`	-	运行时服务地址

示例：

YAML

hope:
  api:
    enable: true
    path: /v3/api-docs
    show-meta: true
    project:
      name: my-api-proto

运行时特点

这些资源都来自 proto 编译生成物，而不是运行时反射扫描：

OpenAPI JSON / YAML
错误码列表
字典列表
权限列表
版本列表

这意味着：

启动更快
输出更稳定
文档与契约始终来自同一份生成结果
如果要修改接口元数据，应该修改 proto 并重新生成，而不是在运行时临时补注解

常见访问地址

Text

Application 'demo-app' is running! Access URLs:

Local                             http://localhost:18089/
External                          http://192.168.0.115:18089/
OAS                               http://192.168.0.115:18089/v3/api-docs
Actuator                          http://192.168.0.115:18089/management
Api-Errors                        http://192.168.0.115:18089/hope/meta/errors
Api-Dictionaries                  http://192.168.0.115:18089/hope/meta/dictionaries
Api-Authorities                   http://192.168.0.115:18089/hope/meta/authorities
Api-Versions                      http://192.168.0.115:18089/hope/meta/versions
Profile(s)                        dev

端点说明

路径	说明
`/v3/api-docs`	最新 OpenAPI JSON
`/v3/api-docs.yaml`	最新 OpenAPI YAML
`/v3/api-docs/{version}`	指定版本 OpenAPI JSON
`/v3/api-docs/{version}.yaml`	指定版本 OpenAPI YAML
`/hope/meta/errors`	错误码清单
`/hope/meta/dictionaries`	字典与常量清单
`/hope/meta/authorities`	权限清单
`/hope/meta/versions`	已发布版本列表

生产环境建议

对外不需要文档时，关闭 hope.api.enable
对外不需要元数据时，关闭 hope.api.showMeta
保持文档和契约一起构建与发布，不要手工维护第二份接口说明

参考

it-common-spring-plus/it-common-spring-api/README.md
hope.common.spring.api.HopeApiProperties
hope.common.spring.api.resource.ApiMetaWebMvcResource
hope.common.spring.api.resource.ApiMetaWebFluxResource

它暴露什么

配置项

运行时特点

常见访问地址

端点说明

生产环境建议

参考

On this page