fix(openapi): vacuum instead of swagger-cli

.github/workflows/ci.yml

@@ -470,26 +470,6 @@ jobs:
           export PATH="$PATH:$HOME/.composer/vendor/bin"
           php-coveralls --coverage_clover=build/logs/behat/clover.xml
         continue-on-error: true
-      - name: Export OpenAPI documents
-        run: |
-          mkdir -p build/out/openapi
-          tests/Fixtures/app/console api:openapi:export -o build/out/openapi/openapi_v3.json
-          tests/Fixtures/app/console api:openapi:export --yaml -o build/out/openapi/openapi_v3.yaml
-      - name: Setup node
-        uses: actions/setup-node@v4
-        with:
-          node-version: '14'
-      - name: Validate OpenAPI documents
-        run: |
-          npx swagger-cli validate build/out/openapi/openapi_v3.json
-          npx swagger-cli validate build/out/openapi/openapi_v3.yaml
-      - name: Upload OpenAPI artifacts
-        if: always()
-        uses: actions/upload-artifact@v4
-        with:
-          name: openapi-docs-php${{ matrix.php }}
-          path: build/out/openapi
-        continue-on-error: true
 
   postgresql:
     name: Behat (PHP ${{ matrix.php }}) (PostgreSQL)
@@ -1272,26 +1252,53 @@ jobs:
           name: behat-logs-php${{ matrix.php }}
           path: build/logs/behat
         continue-on-error: true
+
+  openapi:
+    name: OpenAPI
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      matrix:
+        php:
+          - '8.4'
+      fail-fast: false
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          tools: pecl, composer
+          extensions: intl, bcmath, curl, openssl, mbstring, pdo_sqlite, mongodb
+          ini-values: memory_limit=-1
+      - name: Setup node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      - name: Get composer cache directory
+        id: composercache
+        run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: ${{ steps.composercache.outputs.dir }}
+          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.json') }}
+          restore-keys: ${{ runner.os }}-composer-
+      - name: Update project dependencies
+        run: |
+          composer global require soyuka/pmu
+          composer global config allow-plugins.soyuka/pmu true --no-interaction
+          composer global link .
+      - name: Clear test app cache
+        run: tests/Fixtures/app/console cache:clear --ansi
       - name: Export OpenAPI documents
         run: |
           mkdir -p build/out/openapi
-          tests/Fixtures/app/console api:openapi:export -o build/out/openapi/openapi_v3.json
           tests/Fixtures/app/console api:openapi:export --yaml -o build/out/openapi/openapi_v3.yaml
-      - name: Setup node
-        uses: actions/setup-node@v4
-        with:
-          node-version: '14'
       - name: Validate OpenAPI documents
         run: |
-          npx swagger-cli validate build/out/openapi/openapi_v3.json
-          npx swagger-cli validate build/out/openapi/openapi_v3.yaml
-      - name: Upload OpenAPI artifacts
-        if: always()
-        uses: actions/upload-artifact@v4
-        with:
-          name: openapi-docs-php${{ matrix.php }}
-          path: build/out/openapi
-        continue-on-error: true
+          npx @quobix/vacuum lint -r tests/Fixtures/app/ruleset.yaml build/out/openapi/openapi_v3.yaml -d
 
   laravel:
     name: Laravel (PHP ${{ matrix.php }})

src/OpenApi/Factory/OpenApiFactory.php

@@ -279,7 +279,15 @@
                     continue;
                 }
 
-                $parameter = new Parameter($parameterName, 'path', $uriVariable->getDescription() ?? "$resourceShortName identifier", $uriVariable->getRequired() ?? true, false, false, $uriVariable->getSchema() ?? ['type' => 'string']);
+                $parameter = new Parameter(
+                    $parameterName,
+                    'path',
+                    $uriVariable->getDescription() ?? "$resourceShortName identifier",
+                    $uriVariable->getRequired() ?? true,
+                    false,
+                    null,
+                    $uriVariable->getSchema() ?? ['type' => 'string'],
+                );
 
                 if ($linkParameter = $uriVariable->getOpenApi()) {
                     $parameter = $this->mergeParameter($parameter, $linkParameter);
@@ -329,7 +337,15 @@
                 }
 
                 $in = $p instanceof HeaderParameterInterface ? 'header' : 'query';
-                $defaultParameter = new Parameter($key, $in, $p->getDescription() ?? "$resourceShortName $key", $p->getRequired() ?? false, false, false, $p->getSchema() ?? ['type' => 'string']);
+                $defaultParameter = new Parameter(
+                    $key,
+                    $in,
+                    $p->getDescription() ?? "$resourceShortName $key",
+                    $p->getRequired() ?? false,
+                    false,
+                    null,
+                    $p->getSchema() ?? ['type' => 'string'],
+                );
 
                 $linkParameter = $p->getOpenApi();
                 if (null === $linkParameter) {
@@ -752,15 +768,15 @@
             $description['description'] ?? '',
             $description['required'] ?? false,
             $description['openapi']['deprecated'] ?? false,
-            $description['openapi']['allowEmptyValue'] ?? true,
+            $description['openapi']['allowEmptyValue'] ?? null,
             $schema,
             'array' === $schema['type'] && \in_array(
                 $description['type'],
                 [$arrayValueType, $objectValueType],
                 true
             ) ? 'deepObject' : 'form',
             $description['openapi']['explode'] ?? ('array' === $schema['type']),
-            $description['openapi']['allowReserved'] ?? false,
+            $description['openapi']['allowReserved'] ?? null,
             $description['openapi']['example'] ?? null,
             isset(
                 $description['openapi']['examples']
@@ -777,7 +793,15 @@
         $parameters = [];
 
         if ($operation->getPaginationEnabled() ?? $this->paginationOptions->isPaginationEnabled()) {
-            $parameters[] = new Parameter($this->paginationOptions->getPaginationPageParameterName(), 'query', 'The collection page number', false, false, true, ['type' => 'integer', 'default' => 1]);
+            $parameters[] = new Parameter(
+                $this->paginationOptions->getPaginationPageParameterName(),
+                'query',
+                'The collection page number',
+                false,
+                false,
+                null,
+                ['type' => 'integer', 'default' => 1],
+            );
 
             if ($operation->getPaginationClientItemsPerPage() ?? $this->paginationOptions->getClientItemsPerPage()) {
                 $schema = [
@@ -790,12 +814,28 @@
                     $schema['maximum'] = $maxItemsPerPage;
                 }
 
-                $parameters[] = new Parameter($this->paginationOptions->getItemsPerPageParameterName(), 'query', 'The number of items per page', false, false, true, $schema);
+                $parameters[] = new Parameter(
+                    $this->paginationOptions->getItemsPerPageParameterName(),
+                    'query',
+                    'The number of items per page',
+                    false,
+                    false,
+                    null,
+                    $schema,
+                );
             }
         }
 
         if ($operation->getPaginationClientEnabled() ?? $this->paginationOptions->isPaginationClientEnabled()) {
-            $parameters[] = new Parameter($this->paginationOptions->getPaginationClientEnabledParameterName(), 'query', 'Enable or disable pagination', false, false, true, ['type' => 'boolean']);
+            $parameters[] = new Parameter(
+                $this->paginationOptions->getPaginationClientEnabledParameterName(),
+                'query',
+                'Enable or disable pagination',
+                false,
+                false,
+                null,
+                ['type' => 'boolean'],
+            );
         }
 
         return $parameters;

src/OpenApi/Model/Parameter.php

@@ -17,7 +17,7 @@
 {
     use ExtensionTrait;
 
-    public function __construct(private string $name, private string $in, private string $description = '', private bool $required = false, private bool $deprecated = false, private bool $allowEmptyValue = false, private array $schema = [], private ?string $style = null, private bool $explode = false, private bool $allowReserved = false, private $example = null, private ?\ArrayObject $examples = null, private ?\ArrayObject $content = null)
+    public function __construct(private string $name, private string $in, private string $description = '', private bool $required = false, private bool $deprecated = false, private ?bool $allowEmptyValue = null, private array $schema = [], private ?string $style = null, private bool $explode = false, private ?bool $allowReserved = null, private $example = null, private ?\ArrayObject $examples = null, private ?\ArrayObject $content = null)
     {
         if (null === $style) {
             if ('query' === $in || 'cookie' === $in) {
@@ -53,12 +53,12 @@
         return $this->deprecated;
     }
 
-    public function canAllowEmptyValue(): bool
+    public function canAllowEmptyValue(): ?bool
     {
         return $this->allowEmptyValue;
     }
 
-    public function getAllowEmptyValue(): bool
+    public function getAllowEmptyValue(): ?bool
     {
         return $this->allowEmptyValue;
     }
@@ -83,12 +83,12 @@
         return $this->explode;
     }
 
-    public function canAllowReserved(): bool
+    public function canAllowReserved(): ?bool
     {
         return $this->allowReserved;
     }
 
-    public function getAllowReserved(): bool
+    public function getAllowReserved(): ?bool
     {
         return $this->allowReserved;
     }

src/OpenApi/Tests/Factory/OpenApiFactoryTest.php

@@ -170,7 +170,6 @@
                             in: 'query',
                             description: 'Test modified collection page number',
                             required: false,
-                            allowEmptyValue: true,
                             schema: ['type' => 'integer', 'default' => 1],
                         ),
                     ],
@@ -268,7 +267,7 @@
 
         $baseOperation = (new HttpOperation())->withTypes(['http://schema.example.com/Dummy'])->withInputFormats(self::OPERATION_FORMATS['input_formats'])->withOutputFormats(self::OPERATION_FORMATS['output_formats'])->withClass(Dummy::class)->withShortName('Parameter')->withDescription('This is a dummy');
         $parameterResource = (new ApiResource())->withOperations(new Operations([
-            'uriVariableSchema' => (new Get(uriTemplate: '/uri_variable_uuid', uriVariables: ['id' => new Link(schema: ['type' => 'string', 'format' => 'uuid'], description: 'hello', required: true, openApi: new Parameter('id', 'path', allowEmptyValue: true))]))->withOperation($baseOperation),
+            'uriVariableSchema' => (new Get(uriTemplate: '/uri_variable_uuid', uriVariables: ['id' => new Link(schema: ['type' => 'string', 'format' => 'uuid'], description: 'hello', required: true, openApi: new Parameter('id', 'path'))]))->withOperation($baseOperation),
             'parameters' => (new Put(uriTemplate: '/parameters', parameters: [
                 'foo' => new HeaderParameter(description: 'hi', schema: ['type' => 'string', 'format' => 'uuid']),
             ]))->withOperation($baseOperation),
@@ -477,7 +476,7 @@
                 'type' => 'string',
                 'required' => true,
                 'strategy' => 'exact',
-                'openapi' => new Parameter(in: 'query', name: 'name', example: 'bar', deprecated: true, allowEmptyValue: true, allowReserved: true, explode: true),
+                'openapi' => new Parameter(in: 'query', name: 'name', example: 'bar', deprecated: true, allowReserved: true, explode: true),
             ]]),
             'f2' => new DummyFilter(['ha' => [
                 'property' => 'foo',
@@ -690,16 +689,16 @@
             'Retrieves the collection of Dummy resources.',
             null,
             [
-                new Parameter('page', 'query', 'Test modified collection page number', false, false, true, [
+                new Parameter('page', 'query', 'Test modified collection page number', false, false, null, [
                     'type' => 'integer',
                     'default' => 1,
                 ]),
-                new Parameter('itemsPerPage', 'query', 'The number of items per page', false, false, true, [
+                new Parameter('itemsPerPage', 'query', 'The number of items per page', false, false, null, [
                     'type' => 'integer',
                     'default' => 30,
                     'minimum' => 0,
                 ]),
-                new Parameter('pagination', 'query', 'Enable or disable pagination', false, false, true, [
+                new Parameter('pagination', 'query', 'Enable or disable pagination', false, false, null, [
                     'type' => 'boolean',
                 ]),
             ]
@@ -935,29 +934,29 @@
             'Retrieves the collection of Dummy resources.',
             null,
             [
-                new Parameter('page', 'query', 'The collection page number', false, false, true, [
+                new Parameter('page', 'query', 'The collection page number', false, false, null, [
                     'type' => 'integer',
                     'default' => 1,
                 ]),
-                new Parameter('itemsPerPage', 'query', 'The number of items per page', false, false, true, [
+                new Parameter('itemsPerPage', 'query', 'The number of items per page', false, false, null, [
                     'type' => 'integer',
                     'default' => 30,
                     'minimum' => 0,
                 ]),
-                new Parameter('pagination', 'query', 'Enable or disable pagination', false, false, true, [
+                new Parameter('pagination', 'query', 'Enable or disable pagination', false, false, null, [
                     'type' => 'boolean',
                 ]),
-                new Parameter('name', 'query', '', true, true, true, [
+                new Parameter('name', 'query', '', true, true, null, [
                     'type' => 'string',
                 ], 'form', true, true, 'bar'),
-                new Parameter('ha', 'query', '', false, false, false, [
+                new Parameter('ha', 'query', '', false, false, null, [
                     'type' => 'integer',
                 ]),
-                new Parameter('toto', 'query', '', true, false, false, [
+                new Parameter('toto', 'query', '', true, false, null, [
                     'type' => 'array',
                     'items' => ['type' => 'string'],
                 ], 'deepObject', true),
-                new Parameter('order[name]', 'query', '', false, false, false, [
+                new Parameter('order[name]', 'query', '', false, false, null, [
                     'type' => 'string',
                     'enum' => ['asc', 'desc'],
                 ]),
@@ -981,17 +980,17 @@
             'Retrieves the collection of Dummy resources.',
             null,
             [
-                new Parameter('page', 'query', 'The collection page number', false, false, true, [
+                new Parameter('page', 'query', 'The collection page number', false, false, null, [
                     'type' => 'integer',
                     'default' => 1,
                 ]),
-                new Parameter('itemsPerPage', 'query', 'The number of items per page', false, false, true, [
+                new Parameter('itemsPerPage', 'query', 'The number of items per page', false, false, null, [
                     'type' => 'integer',
                     'default' => 20,
                     'minimum' => 0,
                     'maximum' => 80,
                 ]),
-                new Parameter('pagination', 'query', 'Enable or disable pagination', false, false, true, [
+                new Parameter('pagination', 'query', 'Enable or disable pagination', false, false, null, [
                     'type' => 'boolean',
                 ]),
             ]
@@ -1186,16 +1185,16 @@
             'Retrieves the collection of Dummy resources.',
             null,
             [
-                new Parameter('page', 'query', 'The collection page number', false, false, true, [
+                new Parameter('page', 'query', 'The collection page number', false, false, null, [
                     'type' => 'integer',
                     'default' => 1,
                 ]),
-                new Parameter('itemsPerPage', 'query', 'The number of items per page', false, false, true, [
+                new Parameter('itemsPerPage', 'query', 'The number of items per page', false, false, null, [
                     'type' => 'integer',
                     'default' => 30,
                     'minimum' => 0,
                 ]),
-                new Parameter('pagination', 'query', 'Enable or disable pagination', false, false, true, [
+                new Parameter('pagination', 'query', 'Enable or disable pagination', false, false, null, [
                     'type' => 'boolean',
                 ]),
             ]
@@ -1233,7 +1232,6 @@
         ), $emptyRequestBodyPath->getPost());
 
         $parameter = $paths->getPath('/uri_variable_uuid')->getGet()->getParameters()[0];
-        $this->assertTrue($parameter->getAllowEmptyValue());
         $this->assertEquals(['type' => 'string', 'format' => 'uuid'], $parameter->getSchema());
 
         $parameter = $paths->getPath('/parameters')->getPut()->getParameters()[0];
@@ -1265,16 +1263,16 @@
             'Retrieves the collection of Dummy resources.',
             null,
             [
-                new Parameter('page', 'query', 'The collection page number', false, false, true, [
+                new Parameter('page', 'query', 'The collection page number', false, false, null, [
                     'type' => 'integer',
                     'default' => 1,
                 ]),
-                new Parameter('itemsPerPage', 'query', 'The number of items per page', false, false, true, [
+                new Parameter('itemsPerPage', 'query', 'The number of items per page', false, false, null, [
                     'type' => 'integer',
                     'default' => 30,
                     'minimum' => 0,
                 ]),
-                new Parameter('pagination', 'query', 'Enable or disable pagination', false, false, true, [
+                new Parameter('pagination', 'query', 'Enable or disable pagination', false, false, null, [
                     'type' => 'boolean',
                 ]),
             ],

tests/Fixtures/TestBundle/ApiResource/Crud.php

@@ -23,6 +23,7 @@
 use ApiPlatform\OpenApi\Model\Operation;
 
 #[ApiResource(
+    description: 'A resource used for OpenAPI tests.',
     operations: [
         new Get(),
         new GetCollection(openapi: new Operation(extensionProperties: [OpenApiFactory::API_PLATFORM_TAG => ['internal', 'anotherone']])),