未能將示例添加到 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 )，你只能定義一個例子，並且這個例子必須內聯指定，它不能被$ref引用。

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