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

Question

I am struggling getting the right definition for the request body used from within Symfony Api Platform:

From the image above, what my endpoint is expecting is a JSON containing required values. I am defining required values to be in the path but that is NOT true and they don't belong even to: query, header or cookies.

I have tried two definitions (and I've removed some lines that aren't relevant for the resolution):

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

And the second definition looks like:

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

And here is the result:

None of them seem to be doing what I need or expect, what I am doing wrong? Can I get some help?

I have also read several pages/post without found a good example or the right way to do it (see the following list):

ghry · Accepted Answer

You can use a SwaggerDecorator as described in the docs to override the generated swagger.json and change pretty much anything you like. You will need to edit the definitions for 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"
      },...

or the components.schemas in Openapi v3:

"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"
        },...

Your other option is to use the "swagger_context" ("openapi_context" for openapi v3) of the @ApiResource or @ApiProperty Annotations. Valid options should be in the 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;

Would result in: example doc

Edit: I just noticed that there is an error in your yaml configuration. You are trying to setup the documentation for an array. I assume you want to actually send an object

   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:
                ...

You can check the correct syntax for Data Types here.

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

Answers (1)

Related Questions