如何用go-swagger让@description引用外部Markdown文件？

问题背景 #

我使用go-swagger的swag init命令自动生成swagger.yaml文件，供Redoc读取展示：

swag init -g internal/delivery/rest/router.go --output swagger/ --outputTypes yaml

当前API的@description注解只能硬编码字符串，比如：

// @description "This is a description!"

我希望描述内容来自外部Markdown文件，手动在swagger.yaml中添加如下结构可以实现需求：

description:
  $ref: 'description.md'

但尝试在注解中写// @description file://description.md时，生成的yaml会把它当成普通字符串，而非$ref引用，请问怎么实现这个需求？

解决方案 #

由于go-swagger的@description注解本身不支持直接生成$ref结构，只能通过生成后处理的方式实现，具体步骤如下：

1. 在代码注解中添加自定义标记 #

在需要引用外部Markdown的API注解里，用特殊前缀标记文件路径，比如：

// @description "__DESC_REF__:docs/api/description.md"

2. 在Makefile中添加自动替换步骤 #

在swag init命令之后，用yq（专门处理YAML的命令行工具）扫描生成的swagger.yaml，把标记替换成$ref结构：

swag init -g internal/delivery/rest/router.go --output swagger/ --outputTypes yaml
# 替换所有带__DESC_REF__前缀的描述为$ref引用
yq e '(.paths[][]?.description | select(. | test("^__DESC_REF__:"))) |= {"$ref": . | sub("^__DESC_REF__:"; "")}' swagger/swagger.yaml

补充说明 #

• 未安装yq的话，可通过包管理器安装（如brew install yq或sudo apt install yq）
• 这种方式无需修改go-swagger源码，成本低且易维护
• 若不想用yq，也可以用sed做字符串替换，但sed对YAML嵌套结构的处理不如yq可靠

内容的提问来源于stack exchange，提问作者Matias Barrios