如何从外部文件引用OpenAPI操作的description字段？

当然可以，不过原生OpenAPI规范（OAS 3.x）本身不支持直接引用外部文件里的自由文本字段，需要借助工具链或者模板引擎实现。以下是几种可行方案：

方案1：用OpenAPI专用工具链拆分文件 #

比如Redocly CLI、Swagger CLI这类工具支持拆分OpenAPI文件到多个片段，包括引用自由文本字段：

1. 创建单独的描述文件，比如descriptions/user-get-details.yaml，内容就是纯字符串：

"This API is used to get user details"

2. 在主OpenAPI文件里用$ref引用这个文件：

get:
  tags:
    - User
  summary: Get user details
  description: { $ref: './descriptions/user-get-details.yaml' }
  operationId: updateUser
  parameters:
    - name: userid
      in: path
      description: The id that needs to be pulled
      required: true
      schema:
        type: string

3. 用工具合并成完整的OpenAPI文件，比如Redocly的命令：

redocly bundle openapi.yaml -o bundled-openapi.yaml

方案2：用模板引擎预编译 #

用Handlebars、Nunjucks这类模板引擎，把描述作为变量注入主文件：

1. 把主文件改成模板，比如openapi.hbs：

get:
  tags:
    - User
  summary: Get user details
  description: {{userGetDetailsDesc}}
  operationId: updateUser
  parameters:
    - name: userid
      in: path
      description: The id that needs to be pulled
      required: true
      schema:
        type: string

2. 创建数据文件descriptions.json：

{
  "userGetDetailsDesc": "This API is used to get user details"
}

3. 用模板引擎渲染成最终的YAML文件，比如用Node.js脚本或者命令行工具完成编译。

方案3：用YAML锚点复用描述（适合同/合并文件内复用） #

如果多个操作要复用同一段描述，可以用YAML的锚点功能：

1. 在主文件或者被合并的片段文件里定义锚点：

# 可以放在文件开头或者单独的片段文件中
_reusableDescriptions:
  userGetDetails: &userGetDetails "This API is used to get user details"

2. 在操作里直接引用锚点：

get:
  tags:
    - User
  summary: Get user details
  description: *userGetDetails
  operationId: updateUser
  parameters:
    - name: userid
      in: path
      description: The id that needs to be pulled
      required: true
      schema:
        type: string

这种方式需要确保锚点所在文件被工具合并到主文件中，才能正常解析。

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