“内容”是啥意思：在招摇/openapi“响应”中是啥意思：

Posted 2023-02-19

【中文标题】“内容”是啥意思：在招摇/openapi“响应”中是啥意思：

【英文标题】：what does "content" : mean in swagger/openapi "responses":“内容”是什么意思：在招摇/openapi“响应”中是什么意思：

【发布时间】：2018-01-23 15:48:30

【问题描述】：

使用 Swagger/OpenAPI（以及随后的 swagger-codegen）我无法找到 应该之间的区别

这个，直接来自https://swagger.io/specification/#responsesObject （第一个例子，json格式）

"responses" : 
  "200": 
    "description": "a pet to be returned",
    "content": 
      "application/json": 
        "schema": 
          "$ref": "#/components/schemas/Pet"
    

和

"responses" : 
  "200": 
    "description": "a pet to be returned",
    "schema": 
      "$ref": "#/components/schemas/Pet"
  

我已将此示例放入一个简单的 json swagger 规范 (json) 并运行 Swagger-Codegen (python, flask) 以生成我的控制器和模型。 Yaml 似乎是首选的内部表示，因此当生成器运行时，它会创建一个 yaml 文件。

对于前者，响应类型为“无”

responses:
  200:
    description: "a pet to be returned"

而后者产生了我认为我应该期待的结果：

responses:
  200:
    description: "a pet to be returned"
    schema:
      $ref: "#/components/schemas/Pet"

例如，使用Content 的第一个语法似乎省略了架构

内容是什么意思？ 我从示例中遗漏了什么，为什么 Content 不会导致非无返回类型和相应的架构。

关于 SwaggerCodgen 的注意事项：生成的代码与生成的 yaml 所说的完全匹配，因此我没有在此处包含任何这些细节

【参考方案1】：

第一个示例是 OpenAPI 3.0，第二个示例是 OpenAPI 2.0，因此有所不同。

OpenAPI 3.0 中使用的 content 关键字是 OpenAPI 2.0 中 consumes/produces 的替代品。在responses 的上下文中，content 表示响应具有正文，并指定了响应正文的媒体类型（JSON/XML/等）和结构。

OpenAPI 2.0 版本：

swagger: "2.0"
...
paths:
  /foo:
    get:
      produces:
        - application/json
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/Pet"

OpenAPI 3.0 版本：

openapi: 3.0.0
...
paths:
  /foo:
    get:
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pet"

codegen 问题可能是由以下任一原因引起的：

codegen 尚不支持 OpenAPI 3.0 规范无效（例如，混合使用 2.0 和 3.0 关键字）

【讨论】：

谢谢，我完全错过了。我已经赞成您的答案，一旦我可以使用代码生成器进行验证，就会将其标记为正确。在 3.0 中删除“产品”对我来说似乎更直观，所以我试图在 3.0 而不是 2.0 openapi 中执行此操作。我已经使用 swagger2openapi 将我的 swagger 规范转换为 3.0，但是在 3.0 中获取/运行 codegen 时遇到问题。它似乎在 git 中受支持，但我没有找到任何要运行的预构建 jar 或 docker 容器。

我看到了oss.sonatype.org/content/repositories/snapshots/io/swagger/…，但它失败并且似乎正在执行 2.0 (??) [main] INFO io.swagger.parser.Swagger20Parser - reading from /input/myspec.openapi3.json [main] INFO io.swagger.codegen.ignore.CodegenIgnoreProcessor - No .swagger-codegen-ignore file found. Exception in thread "main" java.lang.RuntimeException: missing swagger input or config!

我建议你在swagger-codegen repo 中打开一个问题。