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

See if this helps: [Describing Request Body in OpenAPI/Swagger 2.0](https://swagger.io/docs/specification/2-0/describing-request-body/), [POST a JSON body with Swagger](https://stackoverflow.com/q/35411628/113116). The last link in your post is also similar to your use case. — Helen, Sep 11 '19 at 15:09
@Helen I am seeing the use of references `$ref: '#/definitions/User'` in almost all the examples (not the ones you shared but all of them) where is suppose I should put those references files in my project? do you have any ideas? — ReynierPM, Sep 11 '19 at 15:14
I'm not familiar with API Platform, sorry. The examples above are how the resulting OpenAPI YAML/JSON file (which is what's loaded into Swagger UI) should look like in order to be rendered properly and for "try it out" to work. — Helen, Sep 11 '19 at 15:22
Want to make your life easy? Then [this](https://stoplight.io/studio/) is a good one. Otherwise, just extract what you need from [here](https://editor.swagger.io/). — BentCoder, Sep 12 '19 at 21:30
@BentCoder that help to build the OpenAPI spec which is fine, the problem is I can't find how to get it working when using [API Platform](https://api-platform.com/) :| — ReynierPM, Sep 13 '19 at 14:06
PAI Platform is a different context now and I don't use it so no clue. — BentCoder, Sep 13 '19 at 14:59

ghry · Accepted Answer · 2019-09-20T13:28:58.057

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?

1 Answers1