Description from OpenApi\Attributes\QueryParameter is not processing

[akankov]

Description from OpenApi\Attributes**QueryParameter** is not processing. nelmio/api-doc-bundle version 5.x-dev and 4.20.0 zircote/swagger-php version 4.8.4

Request class:

<?php
class ExampleRequest
{
    #[OA\QueryParameter(
        description: 'Page number.',
        example: 1,
    )]
    protected int $page = 1;

    public function getPage(): int
    {
        return $this->page;
    }

    public function setPage(int $page): self
    {
        $this->page = $page;

        return $this;
    }
}

Controller:

class ExampleController extends AbstractController
{
    #[Route(path: '', name: 'name', methods: ['GET'])]
    public function listAction(
        #[MapQueryString]
        ExampleRequest $request = new ExampleRequest(),
    ): void {
        // todo do something
    }
}

Result:

{
  "openapi": "3.0.0",
  "info": {
    "title": "title",
    "version": "1.0.0"
  },
  "servers": [],
  "paths": {
    "/": {
      "get": {
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1
            }
          }
        ],
        "responses": {
          "default": {
            "description": ""
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ExampleRequest": {
        "properties": {
          "page": {
            // no description
            "type": "integer",
            "default": 1
          }
        },
        "type": "object"
      }
    },
    "securitySchemes": {
      "Bearer": {
        "type": "http",
        "bearerFormat": "JWT",
        "scheme": "bearer"
      }
    }
  },
  "security": [
    {
      "Bearer": []
    }
  ]
}

[pixelplan-digitalweb]

:+1: I was also wondering if it would be possible to define the parameters on the DTO, would make the action much cleaner

[robertbakker1]

I have a similiar case where the Examples aren't processed:

<?php

use Symfony\Component\Validator\Constraints as Assert;
use OpenApi\Attributes as OA;

final readonly class Sort
{
    public function __construct(
        #[Assert\NotBlank(allowNull: true)]
        public ?string $sort = null,

        #[
            Assert\Choice(choices: ['asc', 'desc']),
            OA\Examples(
                example: "asc",
                summary: "Ascending",
                value: "asc",
            ),
            OA\Examples(
                example: "desc",
                summary: "Descending",
                value: "desc",
            ),
        ]
        public ?string $dir = null,
    )
    {
    }
}

Would make it indeed much cleaner, I will be able to reuse the Sort object in controllers with #[MapQueryString]. My goal is to generate http tests on the openapi spec; using the examples as the input test cases.

[marikn]

@akankov @pixelplan-digitalweb you can achieve it with using OA\Property attribute like this for example:

<?php

class ExampleRequest
{
    #[OA\Property(description: 'Page number.', example: 1)]
    protected int $page = 1;

    public function getPage(): int
    {
        return $this->page;
    }

    public function setPage(int $page): self
    {
        $this->page = $page;

        return $this;
    }
}

and for your @robertbakker1 case:

<?php

use Symfony\Component\Validator\Constraints as Assert;
use OpenApi\Attributes as OA;

final readonly class Sort
{
    public function __construct(
        #[Assert\NotBlank(allowNull: true)]
        public ?string $sort = null,

        #[
            Assert\Choice(choices: ['asc', 'desc']),
            OA\Property(enum: ['asc',  'desc'])
        ]
        public ?string $dir = null,
    )
    {
    }
}