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

Question

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

从上图中，我的endpoint期望的是包含必需值的JSON。我将必需值定义在路径中，但这不是真的，它们甚至不属于：查询、标头或cookie。

我尝试了两种定义（并且删除了一些与解决方案无关的行）：

// 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

结果如下：

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

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

• https://github.com/api-platform/api-platform/issues/1019

Answer 1

您可以使用文档中所述的招摇过市装饰器来覆盖生成的招摇过市。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"
        },...

您的另一个选择是使用@apirource或@ApiProperty注释的“swagger\u上下文”（“openapi\u上下文”用于openapi v3）。有效选项应在swagger文档中。

  /**
   * 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;

将导致：示例文档

编辑：我刚刚注意到您的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:
                ...

您可以在此处检查数据类型的正确语法。