如何在 OpenAPI (Swagger) 中描述这个 POST JSON 请求正文？答案

【问题标题】：How to describe this POST JSON request body in OpenAPI (Swagger)?如何在 OpenAPI (Swagger) 中描述这个 POST JSON 请求正文？
【发布时间】：2015-07-13 18:30:20
【问题描述】：

我有一个使用以下 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"
             }

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

【问题讨论】：

标签： swagger swagger-2.0 openapi

【解决方案1】：

我让它工作了：

    post:
      consumes:
        - application/json
      produces:
        - application/json
        - text/xml
        - text/html
      parameters:
        - name: body
          in: body
          required: true
          schema:
            # Body schema with atomic property examples
            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
            # Alternatively, we can use a schema-level example
            example:
              testapi:
                testapiContext:
                  messageId: kkkk8
                  messageDateTime: '2014-08-17T14:07:30+0530'
                testapiBody:
                  cameraServiceRq:
                    osType: android
                    deviceType: samsung555

【讨论】：

【解决方案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。

【讨论】：

现在，当我在发送请求时复制请求正文中的 json 时，它会将大量 \t 和 \n 附加到我的 json 对象中。如何将干净的 json 发送到后端
有没有办法从外部json文件加载json？
@Webnet YAML 规范中没有关于在 YAML 文档中包含其他文档的内容。因此，如果存在这样的功能，则必须通过读取 YAML 文档的应用程序对某些节点的解释。如果应用程序在 Python 中，这样做非常容易。

【解决方案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
...

【讨论】：

如何以红色显示特定属性类型所需的键。如此处所示 - redocly.github.io/redoc/#operation/newPet。我在properties 中使用了“required：true”类似的东西，但不起作用：属性：名称：类型：字符串描述：所需用户的名称：true