跳到主要内容
版本：0.4.x(Latest)

基本介绍​

APIDocService为源码插件和动态插件提供API文档文本查询能力。源码插件通过services.APIDoc()访问，动态插件通过plugin.yaml声明service: apidoc后使用pluginbridge.Default().APIDoc()客户端访问。该服务把路由操作键解析为本地化的模块标签和操作摘要。

它的典型消费方是操作日志、审计日志或管理端筛选器。这些功能需要把一个请求路由转换为用户可读的业务语义，但不需要接触宿主OpenAPI生成器内部实现。

能力阶段：运行期

类型支持：源码插件、动态插件

能力设计​

操作键构建体系​

操作键是稳定标识，相同业务操作应产生相同操作键，不随路径参数值变化。三种路由类型使用不同的构建策略：

路由类型构建方式示例语义
宿主静态路由BuildOperationKeyFromHandler从DTO类型派生lina-core.backend.api.sys.user.ListReq归一化为core.backend.api.sys.user.ListReq
源码插件路由源码插件包名归一化为plugins.<plugin-id>命名空间避免与宿主或其他插件操作键冲突
动态插件路由BuildOperationKeyFromPath从/x/{pluginId}/...路径和HTTP方法派生生成plugins.{pluginId}.paths.{method}.{path}结构

操作键与翻译目录中的条目对应。ResolveRouteText根据操作键查找翻译目录；命中时返回本地化Title和Summary，未命中时返回调用方提供的回退文本。

翻译目录管理​

翻译目录由宿主管理，APIDocService只负责查询和回退，不负责维护翻译条目。插件路由需要命名空间，源码插件和动态插件路由都进入plugins.<plugin-id>命名空间，避免冲突。

接口定义​

源码插件接口​

方法说明
ResolveRouteText解析单个路由的本地化模块标签和操作摘要
ResolveRouteTexts批量解析多个路由文本，适合批量审计记录
FindRouteTitleOperationKeys按关键词搜索匹配的模块标签操作键

辅助函数：

辅助函数说明
BuildOperationKeyFromHandler从GoFrame严格路由处理函数的请求DTO类型派生操作键
BuildOperationKeyFromPath从规范化路径和HTTP方法派生操作键
BuildDynamicOperationKey动态插件路由操作键构建入口

动态插件接口​

动态插件通过hostServices.apidoc声明授权的方法：

动态方法说明
route_text.resolve解析单个路由的本地化模块标签和操作摘要
route_texts.resolve批量解析多个路由文本
route_title_operation_keys.find按关键词搜索匹配的模块标签操作键

能力使用​

源码插件使用​

源码插件通过services.APIDoc()解析路由文本，典型场景包括审计日志记录和管理端筛选：

// 解析单个路由的文档文本
text := services.APIDoc().ResolveRouteText(ctx, apidoccap.RouteTextInput{
    OperationKey:    operationKey,
    FallbackTitle:   fallbackTitle,
    FallbackSummary: fallbackSummary,
})

// 批量解析多个路由文本
texts := services.APIDoc().ResolveRouteTexts(ctx, inputs)

// 按关键词搜索匹配的操作键
keys := services.APIDoc().FindRouteTitleOperationKeys(ctx, keyword)

辅助函数用于构建操作键：

// 从DTO类型构建操作键
key := apidoc.BuildOperationKeyFromHandler(handlerFunc)

// 从路径构建操作键
key := apidoc.BuildOperationKeyFromPath("/api/users", "GET")

动态插件使用​

动态插件在plugin.yaml中声明apidoc服务和授权方法：

hostServices:
  - service: apidoc
    methods:
      - route_text.resolve
      - route_texts.resolve

动态插件通过pluginbridge.Default().APIDoc()客户端调用：

apiDocSvc := pluginbridge.Default().APIDoc()

// 解析单个路由的文档文本
text := apiDocSvc.ResolveRouteText(ctx, apidoccap.RouteTextInput{
    OperationKey:    operationKey,
    FallbackTitle:   fallbackTitle,
    FallbackSummary: fallbackSummary,
})

// 批量解析多个路由文本
texts := apiDocSvc.ResolveRouteTexts(ctx, inputs)

设计约束​

  • 操作键是稳定标识。 相同业务操作应产生相同操作键，不随路径参数值变化。
  • 翻译目录由宿主管理。 APIDocService只负责查询和回退，不负责维护翻译条目。
  • 插件路由需要命名空间。 源码插件和动态插件路由都进入plugins.<plugin-id>命名空间，避免冲突。
  • 回退文本必须可读。 未命中翻译时会返回调用方回退文本，审计日志仍应有可展示内容。

相关服务​