无法将示例添加到 YAML 文件

Question

目的：将示例添加到 yaml 文件中，以便在 Postman 集合中公开。

我正在尝试添加 2 个简单示例，但不断出现错误。当前错误是：流集合条目之间缺少逗号。

你能帮忙吗？

swagger: "2.0"
info:
  description: "Test"
  version: "1.4.4"
  title: "my-test"
host: "somehost"
basePath: "/somepath"
schemes:
- "https"
tags:
  - name: Recommend
    description: helloWorld

paths:

  /hello:
    post:
      description: "some description"
      operationId: "example-test"
      tags: ["example-test"]
      produces:
       "application/json"
      parameters:
        name: "myRequest"
        in: "body"
        description: "bla"
        required: true
        schema:
          $ref: "#/definitions/myRequest"
        examples: {ex1: $ref: "#/components/examples/test1" , ex2: $ref: "#/components/examples/test2" }
      responses:
        "204":
          description: "All good"

definitions:
  myRequest:
    type: object
    required: 
    - name
    - lastname
    properties:
      name:
        type: string
      lastname:
        type: string
        
components:
    examples:
      test1:
        value:
          name: test1
          lastname: test1
      test2:
        value:
          name: test2
          lastname: test2

    
    
    
  

Answer 1

您混淆了 OpenAPI 2.0 和 3.0 语法。

仅 OpenAPI 3.0 支持多个 examples。正确的语法是：

openapi: 3.0.0
...

paths:
  /hello:
    post:
      description: "some description"
      operationId: "example-test"
      tags: ["example-test"]

      requestBody:     # <------
        required: true
        content:
          application/json:
            schema:
               $ref: "#/components/schemas/myRequest"
            examples:  # <------
              ex1:
                $ref: "#/components/examples/test1"
              ex2:
                $ref: "#/components/examples/test2"
      responses:
        "204":
          description: "All good"

components:
  schemas:
    myRequest:
      ...
  examples:
    test1:
      value:
        name: test1
        lastname: test1
    test2:
      value:
        name: test2
        lastname: test2

如果使用 OpenAPI 2.0 (swagger: '2.0)，则只能定义单个示例，并且此示例必须内联指定，不能为 $referenced。

swagger: "2.0"
...

paths:
  /hello:
    post:
      description: "some description"
      operationId: "example-test"
      tags: ["example-test"]
      produces:
        - "application/json"  # <---- Note the leading dash here
      parameters:
        - name: "myRequest"   # <---- Note the leading dash here
          in: "body"
          description: "bla"
          required: true
          schema:
            $ref: "#/definitions/myRequest"
      responses:
        "204":
          description: "All good"

definitions:
  myRequest:
    type: object
    required: 
      - name
      - lastname
    properties:
      name:
        type: string
      lastname:
        type: string
    example:           # <---- Example value for a schema
      name: test1
      lastname: test1