如何在Swagger特定路径下隐藏指定$ref属性且无需新建模型
Swagger文档按需裁剪模型属性的实现方案
针对你使用的OpenAPI 2.0(Swagger 2.0)语法,没有直接在$ref引用后单独过滤属性的内置配置,但可以通过标准的schema组合能力实现零冗余的按需隐藏,完全不需要新建独立的重复模型。
核心实现:allOf组合式属性排除
不需要在全局definitions里重复抄写FunctionTitle的所有通用字段定义,直接在需要精简返回的接口响应位置,通过allOf组合基础模型+属性排除规则即可,修改后的/periods接口响应配置如下:
/periods: get: tags: - developers & users summary: Periods operationId: periods description: | By passing in the appropriate options, you can search for available inventory in the system produces: - application/json responses: 200: description: search matching criteria schema: type: object properties: periods: type: array items: allOf: # 完整复用原有FunctionTitle的所有属性定义 - $ref: '#/definitions/FunctionTitle' # 声明需要从最终合并的schema中排除的属性 - type: object properties: org: false funcType: false 400: description: bad input parameter
方案特性
- 零冗余代码:完全继承原有
FunctionTitle模型的字段类型、格式、必填规则、示例值,不需要重复编写任何已有字段的配置 - 配置自动同步:后续如果基础模型调整字段、修改示例值,所有使用该组合schema的接口会自动同步变更,不会出现多份模型定义不一致的问题
- 工具链全兼容:该写法是OpenAPI规范明确支持的schema合并规则,Swagger UI、接口代码生成器、文档校验工具都可以正确识别,最终渲染的响应结构会自动移除
org和funcType,和你预期的返回示例完全一致
注意事项
- 原有
FunctionTitle模型中org、funcType本来就不在required必填列表内,排除这两个属性不会触发任何schema校验异常 - 如果后续多个接口都需要复用这个精简版的
FunctionTitle结构,只需要把这段组合schema移到全局definitions下命名为独立条目即可,依然不需要抄写重复的字段定义
内容的提问来源于stack exchange,提问作者hrondor
相关产品推荐
相关产品推荐

