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

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

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.