Question

我有一个使用以下JSON请求正文的POST请求。如何使用OpenAPI（Swagger）描述此请求体？

{
    "testapi": {
        "testapiContext": {
            "messageId": "kkkk8",
            "messageDateTime": "2014-08-17T14:07:30+0530"
        },
        "testapiBody": {
            "cameraServiceRq": {
                "osType": "android",
                "deviceType": "samsung555"
            }
        }
    }
}

到目前为止，我尝试了以下内容，但我仍然坚持定义正文schema。

swagger: "2.0"
info:
  version: 1.0.0
  title: get camera
  license:
    name: MIT
host: localhost
basePath: /test/service
schemes:
  - http
consumes:
  - application/json
produces:
  - application/json
paths:
  /getCameraParameters:
    post:
      summary: Create new parameters
      operationId: createnew
      consumes:
        - application/json
        - application/xml
      produces:
        - application/json
        - application/xml
      parameters:
        - name: pet
          in: body
          description: The pet JSON you want to post
          schema:  # <--- What do I write here?

          required: true
      responses: 
        200: 
          description: "200 response"
          examples: 
            application/json: 
             {
               "status": "Success"
             }

我想将输入体内联定义，作为文档的示例。

Answer 1

我使用了它：

{{1}}

Answer 2

在YAML中包含多行标量的最易读的方法是使用block literal style。这要求您仅使用缩进更改您的JSON示例（如果您检索键的值，将删除它）：

.
.
produces:
  - application/json
example: |
  {
      "testapi": {
          "testapiContext": {
              "messageId": "kkkk8",
              "messageDateTime": "2014-08-17T14:07:30+0530"
     },
          "testapiBody": {
              "cameraServiceRq": {
                  "osType": "android",
                  "deviceType": "samsung555"
              }
          }
      }
  }
paths:
  /getCameraParameters:
.
.

（为清楚起见，您可以在paths标量键之前添加一两个额外的换行符，它们会在文字块样式标量上得到clipped by default。

Answer 3

openapi 版本 >= 3.0.0 允许使用 requestBody，这将允许 parameters 之外的请求正文定义。

在你的情况下，它看起来像这样：

...
      requestBody:
        description: The pet JSON you want to post
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                testapi:
                  type: object
                  properties:
                    messageId:
                      type: string
                      example: kkkk8
                    messageDateTime:
                      type: string
                      example: '2014-08-17T14:07:30+0530'
                testapiBody:
                  type: object
                  properties:
                    cameraServiceRq:
                      type: object
                      properties:
                        osType:
                          type: string
                          example: android
                        deviceType:
                          type: string
                          example: samsung555
              example:
                testapi:
                  testapiContext:
                    messageId: kkkk8
                    messageDateTime: '2014-08-17T14:07:30+0530'
                  testapiBody:
                    cameraServiceRq:
                      osType: android
                      deviceType: samsung555
...

如何在OpenAPI（Swagger）中描述此POST JSON请求主体？

3 个答案: