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

Question

中使用的请求主体获取正确的定义

从上图中，我的端点期望的是包含所需值的 JSON。我正在定义 path 中的必需值，但那是 NOT true 并且它们甚至不属于：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

结果如下：

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

我也阅读了几本 pages/post，但没有找到好的示例或正确的方法（请参阅以下列表）：

Answer 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_context" for openapi v3）。有效选项应在 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 的正确语法。

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

How to describe request body properly using OpenAPI and API Platform?

symfony

swagger

openapi

api-platform.com