RapiDoc中如何控制请求头示例值的自动填充

在API文档工具RapiDoc中，默认情况下如果OpenAPI规范(OAS)中定义了header参数的示例值(example)，这些示例值会自动填充到对应的请求头输入框中。这种自动填充行为虽然方便，但在某些场景下可能并不符合用户需求。

全局控制示例填充

RapiDoc提供了一个名为fill-request-fields-with-example的全局属性，可以控制是否自动填充所有请求参数的示例值。这包括查询参数(query)、路径参数(path)、请求头(header)、请求体(request-body)和cookie参数。

在HTML标签中设置该属性为true即可启用全局自动填充：

<rapi-doc id="thedoc" spec-url="./specs/temp.yaml" fill-request-fields-with-example="true"></rapi-doc>

细粒度控制特定参数

当启用全局自动填充后，如果需要对特定参数禁用此功能，可以使用RapiDoc的vendor扩展x-fill-example。在OpenAPI规范中，为不需要自动填充的参数添加此扩展并设置为"no"即可。

例如，在YAML规范中可以这样定义：

parameters:
  - name: x-api-key
    in: header
    example: my-secret
    x-fill-example: no
    schema:
      type: string

这样配置后，虽然全局启用了示例自动填充，但x-api-key这个请求头参数将不会自动填充示例值。

实际应用场景

这种细粒度控制在实际开发中非常有用：

1. 安全性考虑：对于包含敏感信息的请求头(如API密钥)，开发者可能不希望自动显示示例值
2. 用户体验：某些参数可能需要用户手动输入而非使用预设值
3. 测试场景：在自动化测试中可能需要控制哪些参数使用固定示例值

通过合理使用全局设置和vendor扩展，开发者可以灵活控制RapiDoc中示例值的展示行为，既保证了文档的易用性，又能满足各种特殊需求。