加入範例

您可以將範例新增至參數、屬性和物件，使您的 Web 服務的 OpenAPI 規格更清晰。處理 API 的工具和程式庫可以讀取範例。例如，API 模擬工具可以使用範例值來產生模擬請求。您可以為物件、個別屬性和操作參數指定範例。若要指定範例，您可以使用 example 或 examples 鍵。詳細資訊請見下方。

針對 Swagger UI 使用者的注意事項： 自 Swagger UI 3.23.0 和 Swagger Editor 3.6.31 起，支援多個 examples。

注意： 請勿將範例值與預設值混淆。範例說明值應該是什麼。預設值是如果用戶端未提供值時，伺服器所使用的值。

參數範例

以下是一個參數值的範例

1
parameters:
2
  - in: query
3
    name: status
4
    schema:
5
      type: string
6
      enum: [approved, pending, closed, new]
7
      example: approved # Example of a parameter value

參數的多個範例

1
parameters:
2
  - in: query
3
    name: limit
4
    schema:
5
      type: integer
6
      maximum: 50
7
    examples: # Multiple examples
8
      zero: # Distinct name
9
        value: 0 # Example value
10
        summary: A sample limit value # Optional description
11
      max: # Distinct name
12
        value: 50 # Example value
13
        summary: A sample limit value # Optional description

如您所見，每個範例都有一個不同的鍵名。此外，在上面的程式碼中，我們使用了具有描述的選用 summary 鍵。注意：您指定的範例值應與參數資料類型相符。

請求和回應主體範例

以下是請求主體中 example 關鍵字的範例

1
paths:
2
  /users:
3
    post:
4
      summary: Adds a new user
5
      requestBody:
6
        content:
7
          application/json:
8
            schema: # Request body contents
9
              type: object
10
              properties:
11
                id:
12
                  type: integer
13
                name:
14
                  type: string
15
              example: # Sample object
16
                id: 10
17
                name: Jessica Smith
18
      responses:
19
        "200":
20
          description: OK

請注意，在上面的程式碼中，example 是 schema 的子項。如果 schema 指的是 components 區段中定義的某些物件，則應將 example 設定為媒體類型關鍵字的子項

1
paths:
2
  /users:
3
    post:
4
      summary: Adds a new user
5
      requestBody:
6
        content:
7
          application/json: # Media type
8
            schema: # Request body contents
9
              $ref: "#/components/schemas/User" # Reference to an object
10
            example: # Child of media type because we use $ref above
11
              # Properties of a referenced object
12
              id: 10
13
              name: Jessica Smith
14
      responses:
15
        "200":
16
          description: OK

這是必要的，因為 $ref 會覆寫它旁邊的所有同級元素。如果需要，您可以使用多個範例

1
paths:
2
  /users:
3
    post:
4
      summary: Adds a new user
5
      requestBody:
6
        content:
7
          application/json: # Media type
8
            schema: # Request body contents
9
              $ref: "#/components/schemas/User" # Reference to an object
10
            examples: # Child of media type
11
              Jessica: # Example 1
12
                value:
13
                  id: 10
14
                  name: Jessica Smith
15
              Ron: # Example 2
16
                value:
17
                  id: 11
18
                  name: Ron Stewart
19
      responses:
20
        "200":
21
          description: OK

以下是回應主體中 example 的範例

1
responses:
2
  "200":
3
    description: A user object.
4
    content:
5
      application/json:
6
        schema:
7
          $ref: "#/components/schemas/User" # Reference to an object
8
        example:
9
          # Properties of the referenced object
10
          id: 10
11
          name: Jessica Smith

回應主體中的多個範例

1
responses:
2
  "200":
3
    description: A user object.
4
    content:
5
      application/json:
6
        schema:
7
          $ref: "#/components/schemas/User" # Reference to an object
8
        examples:
9
          Jessica:
10
            value:
11
              id: 10
12
              name: Jessica Smith
13
          Ron:
14
            value:
15
              id: 20
16
              name: Ron Stewart

注意：回應和請求主體中的範例是自由格式的，但應與主體架構相容。

物件和屬性範例

您也可以在 components 區段中為物件和個別屬性指定範例。

屬性層級範例

1
components:
2
  schemas:
3
    User: # Schema name
4
      type: object
5
      properties:
6
        id:
7
          type: integer
8
          format: int64
9
          example: 1 # Property example
10
        name:
11
          type: string
12
          example: New order # Property example

物件層級範例

1
components:
2
  schemas:
3
    User: # Schema name
4
      type: object
5
      properties:
6
        id:
7
          type: integer
8
        name:
9
          type: string
10
      example: # Object-level example
11
        id: 1
12
        name: Jessica Smith

請注意，架構和屬性支援單個 example，但不支援多個 examples。

陣列範例

您可以新增個別陣列項目的範例

1
components:
2
  schemas:
3
    ArrayOfInt:
4
      type: array
5
      items:
6
        type: integer
7
        format: int64
8
        example: 1

或包含多個項目的陣列層級範例

1
components:
2
  schemas:
3
    ArrayOfInt:
4
      type: array
5
      items:
6
        type: integer
7
        format: int64
8
      example: [1, 2, 3]

如果陣列包含物件，您可以按如下方式指定多項目範例

1
components:
2
  schemas:
3
    ArrayOfUsers:
4
      type: array
5
      items:
6
        type: object
7
        properties:
8
          id:
9
            type: integer
10
          name:
11
            type: string
12
      example:
13
        - id: 10
14
          name: Jessica Smith
15
        - id: 20
16
          name: Ron Stewart

請注意，陣列和陣列項目支援單個 example，但不支援多個 examples。

XML 和 HTML 資料的範例

若要描述無法以 JSON 或 YAML 格式呈現的範例值，請將其指定為字串

1
content:
2
  application/xml:
3
    schema:
4
      $ref: "#/components/schemas/xml"
5
    examples:
6
      xml:
7
        summary: A sample XML response
8
        value: "<objects><object><id>1</id><name>new</name></object><object><id>2</id></object></objects>"
9
  text/html:
10
    schema:
11
      type: string
12
    examples:
13
      html:
14
        summary: A list containing two items
15
        value: "<html><body><ul><li>item 1</li><li>item 2</li></ul></body></html>"

您可以在此 Stack Overflow 文章中找到關於在 YAML 中撰寫多行字串的資訊：https://stackoverflow.com/questions/3790454/in-yaml-how-do-i-break-a-string-over-multiple-lines。

外部範例

如果由於某些原因無法將範例值插入您的規格，例如，它既不符合 YAML 也不符合 JSON，您可以使用 externalValue 關鍵字來指定範例值的 URL。URL 應指向包含文字範例內容的資源（例如，物件、檔案或影像）

1
content:
2
  application/json:
3
    schema:
4
      $ref: "#/components/schemas/MyObject"
5
    examples:
6
      jsonObject:
7
        summary: A sample object
8
        externalValue: "http://example.com/examples/object-example.json"
9
  application/pdf:
10
    schema:
11
      type: string
12
      format: binary
13
    examples:
14
      sampleFile:
15
        summary: A sample file
16
        externalValue: "http://example.com/examples/example.pdf"

重複使用範例

您可以在規格的 components/examples 區段中定義常見的範例，然後在各種參數描述、請求和回應主體描述、物件和屬性中重複使用它們

1
    content:
2
      application/json:
3
        schema:
4
          $ref: '#/components/schemas/MyObject'
5
        examples:
6
          objectExample:
7
            $ref: '#/components/examples/objectExample'
8
    ...
9
    components:
10
      examples:
11
        objectExample:
12
          value:
13
            id: 1
14
            name: new object
15
          summary: A sample object

找不到您要找的內容嗎？向社群提問
發現錯誤？告訴我們