如何使用 OpenAPI 和 API 平台正确描述请求正文？答案

【问题标题】：How to describe request body properly using OpenAPI and API Platform?如何使用 OpenAPI 和 API 平台正确描述请求正文？
【发布时间】：2020-01-13 11:09:00
【问题描述】：

我正在努力为 Symfony Api Platform 中使用的请求正文获得正确的定义：

从上图中，我的端点期望的是一个包含所需值的 JSON。我将要求的值定义在 path 中，但这是 NOT 正确的，它们甚至不属于：query、header 或 cookies。

我尝试了两个定义（并且我删除了一些与分辨率无关的行）：

// the definition result is on the first image on this post
resources:
  App\Entity\Cases:
    collectionOperations:
      case_assign:
        swagger_context:
          parameters:
            - name: assign_type
              in: path
              description: 'The assignee type: worker or reviewer'
              required: true
              type: string
            // ....
            - in: body
              name: body
              description: 'Object needed to perform a case assignment'
              required: true
              example: {
                          "assign_type": "worker",
                          "assigned_by": 1,
                          "assigned_to": 1,
                          "cases": {
                            "0": 109855,
                            "1": 109849,
                            "2": 109845
                          }
                        }

第二个定义如下：

resources:
  App\Entity\Cases:
    collectionOperations:
      case_assign:
        swagger_context:
          summary: 'Assign a worker or a reviewer to a case'
          parameters:
            - name: body
              in: body
              required: true
              schema:
                type: array
                items:
                  assign_type:
                    name: assign_type
                    description: 'The assignee type: worker or reviewer'
                    required: true
                    type: string

结果如下：

他们似乎都没有做我需要或期望的事情，我做错了什么？我能得到一些帮助吗？

我也阅读了几页/帖子，但没有找到一个很好的例子或正确的方法（请参阅以下列表）：

【问题讨论】：

看看这是否有帮助：Describing Request Body in OpenAPI/Swagger 2.0，POST a JSON body with Swagger。您帖子中的最后一个链接也与您的用例类似。
@Helen 我在几乎所有示例（不是您共享的示例，而是所有示例）中都看到了引用 $ref: '#/definitions/User' 的使用，假设我应该将这些引用文件放在我的项目中吗？你有什么想法吗？
我对 API 平台不熟悉，抱歉。上面的示例是生成的 OpenAPI YAML/JSON 文件（加载到 Swagger UI 中的文件）的外观，以便正确呈现和“试用”工作。
想让您的生活更轻松吗？那么this 是一个不错的选择。否则，只需从 here 中提取您需要的内容。
@BentCoder 帮助构建 OpenAPI 规范，这很好，问题是我在使用 API Platform 时找不到如何让它工作：|

标签： symfony swagger openapi api-platform.com

【解决方案1】：

您可以使用文档中所述的SwaggerDecorator 来覆盖生成的 swagger.json 并更改几乎任何您喜欢的内容。您将需要编辑 v2 的定义

"paths": {
  "/todos": {
    "post": {
      "parameters": [
        {
          "name": "todo",
          "in": "body",
          "description": "The new Todo resource",
          "schema": {
            "$ref": "#/definitions/Todo"
          }
        }
      ]
}}}
"definitions": {
  "Todo": {
    "type": "object",
    "description": "",
    "properties": {
      "text": {
        "required": true,
        "description": "This text will be added to the schema as a description",
        "type": "string"
      },...

或 Openapi v3 中的 components.schemas：

"components": {
  "schemas": {
    "Todo": {
      "type": "object",
      "description": "",
      "properties": {  
        "text": {
          "required": true,
          "minLength": 4,
          "example": "some example text",
          "description": "This text will be added to the schema as a description",
          "type": "string"
        },...

您的另一个选择是使用@ApiResource 或@ApiProperty 注释的“swagger_context”（openapi v3 的“openapi_context”）。有效选项应位于swagger docs。

  /**
   * This text will be added to the schema as a description
   * @ApiProperty(
   *     swaggerContext={"required"=true},
   *     openapiContext={"required"=true, "minLength"=4, "example"="some example text"})
   * @ORM\Column(type="string", length=255)
   */
  private $text;

会导致： example doc

编辑：我刚刚注意到您的 yaml 配置中有错误。您正在尝试为阵列设置文档。我假设你想实际发送一个对象

   parameters:
        - name: body
          in: body
          required: true
          schema:
            type: object
            required:             #only for swagger v2
               - assign_type
            properties:
              assign_type:
                description: 'The assignee type: worker or reviewer'
                required: true    #only for openapi v3
                type: string
              assigned_by:
                ...

您可以检查Data Types here 的正确语法。

【讨论】：