OpenAPI POST请求体Schema引用已定义模型失效如何解决？

你的配置存在三处关键错误，导致Swagger无法加载name_translation对应的模型结构：

1. Body参数错误指定type: string #

在OpenAPI规范中，in: body类型的参数不需要设置type属性，直接通过schema定义请求体结构即可。多余的type: string会干扰Swagger对请求体的解析逻辑。

2. name_translation的引用格式不符合规范 #

引用已定义的模型时，无需嵌套schema字段，直接使用$ref指向目标模型即可。你当前嵌套schema的写法不符合OpenAPI的结构要求。

3. NameTranslations模型的定义位置和格式有误 #

模型必须放在根节点的definitions（OpenAPI 2.0）或components/schemas（OpenAPI 3.0）下，同时要保证YAML的缩进格式正确，否则Swagger无法识别该模型。

修复后的完整代码示例（OpenAPI 2.0） #

swagger: "2.0"
info:
  title: Plant API
  version: "1.0.0"
paths:
  /plant-units:
    post:
      summary: "Creates a new Plant Unit."
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - name: plantunit
          in: body
          required: true
          schema:
            type: object
            required:
              - plant_guid
              - code
            properties:
              code:
                type: string
              plant_guid:
                type: string
              parent_guid:
                type: string
              name_translation:
                $ref: '#/definitions/NameTranslations' # 直接引用目标模型
definitions:
  NameTranslations: # 模型必须放置在definitions节点下
    type: object
    properties:
      EN: 
        type: string
      ES:
        type: string
      PT: 
        type: string

关键修复点总结 #

• 删除body参数中的type: string配置
• 将name_translation下的type: object和嵌套schema替换为直接的$ref引用
• 确保NameTranslations模型正确放置在definitions节点内，YAML缩进符合格式要求

内容的提问来源于stack exchange，提问作者Fabio Mendes Soares