如何在 swagger 的成功 GET 響應中記錄多種內容類型

Question

假設我們有一個示例 json swagger 規范：

{
"swagger": "2.0",
"info": {
    "version": "1.0.0",
    "title": "Some API"
},
"basePath": "/api/v1",
"consumes": [
    "application/json"
],
"produces": [
    "application/json",
    "text/csv"
],
"paths": {
    "/some/endpoint": {
        "get": {
            "parameters": [
                {
                    "in": "body",
                    "name": "body",
                    "required": false,
                    "schema": {
                      "$ref": "#/definitions/BodyParamsDefinition"
                    }
                }
            ],
            "responses": {
                "200": { ?? } ...

可以生成兩種內容類型：

• 應用程序/json
• 文本/csv

GET /some/endpoint默認響應是一個 csv 文件，但如果像這樣使用format查詢參數/some/endpoint?format=json ，則響應將采用 json 格式。

我很難找到如何以正確的響應完成我的規范。 當我使用這種方法時： https://swagger.io/docs/specification/describing-responses/我得到一個驗證錯誤： ...get.responses['200'] should NOT have additional properties

Answer 1

您就快完成了，您只需要為響應定義一個schema 。 此schema定義與此狀態代碼關聯的所有內容類型的響應結構。

例如，如果操作返回此 JSON：

[
  {
    "petType": "dog",
    "name": "Fluffy"
  },
  {
    "petType": "cat",
    "name": "Crookshanks"
  }
]

和這個CSV：

petType,name
dog,Fluffy
cat,Crookshanks

你會使用：

# YAML
responses:
  200:
    description: OK
    schema:
      type: array
      items:
        type: object
        properties:
          petType:
            type: string
          name:
            type: string

更多信息：描述響應

在 OpenAPI 3.0 中，改進了內容類型定義，並且架構可以因內容類型而異：

openapi: 3.0.0
...

paths:
  /some/endpoint:
    get:
      responses:
       '200':
          description: OK
          content:
            # JSON data is an object
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
            # CSV data is a string of text
            text/csv:
              schema:
                type: string

GET /some/endpoint默認響應是一個 csv 文件，但如果像這樣使用format查詢參數/some/endpoint?format=json ，則響應將采用 json 格式。

目前無法將特定響應映射到特定操作參數，但 OpenAPI 規范存儲庫中有幾個相關的建議：

• 通過允許路徑中的查詢參數來容納遺留 API
• 路徑規范中的查詢字符串
• 支持一個操作每個路徑有多個規范
• 超載