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

Question

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



从上图中，我的端点期望的是包含所需值的 JSON。我将所需的值定义为 path但那是 不是 真的，它们甚至不属于: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

结果如下:



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

我还阅读了几页/帖子，但没有找到一个好的例子或正确的方法(请参阅以下列表):

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

https://api-platform.com/docs/core/swagger/

https://idratherbewriting.com/learnapidoc/pubapis_swagger_intro.html

https://swagger.io/docs/specification/describing-parameters/

https://swagger.io/docs/specification/describing-request-body/

How to describe this POST JSON request body in OpenAPI (Swagger)?

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 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 的正确语法.