feat(openapi): reflect specification to OpenAPI 3.1

.github/workflows/ci.yml

@@ -309,10 +309,10 @@ jobs:
           tests/Fixtures/app/console api:openapi:export --spec-version=3 --yaml -o build/out/openapi/openapi_v3.yaml
       - name: Validate OpenAPI documents
         run: |
-            npx swagger-cli validate build/out/openapi/swagger_v2.json
-            npx swagger-cli validate build/out/openapi/swagger_v2.yaml
-            npx swagger-cli validate build/out/openapi/openapi_v3.json
-            npx swagger-cli validate build/out/openapi/openapi_v3.yaml
+            npx git+https://github.com/soyuka/swagger-cli#master validate build/out/openapi/swagger_v2.json
+            npx git+https://github.com/soyuka/swagger-cli#master validate build/out/openapi/swagger_v2.yaml
+            npx git+https://github.com/soyuka/swagger-cli#master validate build/out/openapi/openapi_v3.json
+            npx git+https://github.com/soyuka/swagger-cli#master validate build/out/openapi/openapi_v3.yaml
       - name: Upload OpenAPI artifacts
         if: always()
         uses: actions/upload-artifact@v1
@@ -875,10 +875,10 @@ jobs:
           tests/Fixtures/app/console api:openapi:export --spec-version=3 --yaml -o build/out/openapi/openapi_v3.yaml
       - name: Validate OpenAPI documents
         run: |
-          npx swagger-cli validate build/out/openapi/swagger_v2.json
-          npx swagger-cli validate build/out/openapi/swagger_v2.yaml
-          npx swagger-cli validate build/out/openapi/openapi_v3.json
-          npx swagger-cli validate build/out/openapi/openapi_v3.yaml
+          npx git+https://github.com/soyuka/swagger-cli#master validate build/out/openapi/swagger_v2.json
+          npx git+https://github.com/soyuka/swagger-cli#master validate build/out/openapi/swagger_v2.yaml
+          npx git+https://github.com/soyuka/swagger-cli#master validate build/out/openapi/openapi_v3.json
+          npx git+https://github.com/soyuka/swagger-cli#master validate build/out/openapi/openapi_v3.yaml
       - name: Upload OpenAPI artifacts
         if: always()
         uses: actions/upload-artifact@v1
@@ -1089,7 +1089,7 @@ jobs:
           tests/Fixtures/app/console api:openapi:export --spec-version=3 --yaml -o build/out/openapi/openapi_v3.yaml
       - name: Validate OpenAPI documents
         run: |
-            npx swagger-cli validate build/out/openapi/swagger_v2.json
-            npx swagger-cli validate build/out/openapi/swagger_v2.yaml
-            npx swagger-cli validate build/out/openapi/openapi_v3.json
-            npx swagger-cli validate build/out/openapi/openapi_v3.yaml
+            npx git+https://github.com/soyuka/swagger-cli#master validate build/out/openapi/swagger_v2.json
+            npx git+https://github.com/soyuka/swagger-cli#master validate build/out/openapi/swagger_v2.yaml
+            npx git+https://github.com/soyuka/swagger-cli#master validate build/out/openapi/openapi_v3.json
+            npx git+https://github.com/soyuka/swagger-cli#master validate build/out/openapi/openapi_v3.yaml

features/openapi/docs.feature

@@ -10,7 +10,7 @@ Feature: Documentation support
     And the response should be in JSON
     And the header "Content-Type" should be equal to "application/json; charset=utf-8"
     # Context
-    And the JSON node "openapi" should be equal to "3.0.3"
+    And the JSON node "openapi" should be equal to "3.1.0"
     # Root properties
     And the JSON node "info.title" should be equal to "My Dummy API"
     And the JSON node "info.description" should contain "This is a test API."

src/Core/OpenApi/Model/Components.php

@@ -26,8 +26,9 @@ final class Components
     private $securitySchemes;
     private $links;
     private $callbacks;
+    private $pathItems;
 
-    public function __construct(\ArrayObject $schemas = null, \ArrayObject $responses = null, \ArrayObject $parameters = null, \ArrayObject $examples = null, \ArrayObject $requestBodies = null, \ArrayObject $headers = null, \ArrayObject $securitySchemes = null, \ArrayObject $links = null, \ArrayObject $callbacks = null)
+    public function __construct(\ArrayObject $schemas = null, \ArrayObject $responses = null, \ArrayObject $parameters = null, \ArrayObject $examples = null, \ArrayObject $requestBodies = null, \ArrayObject $headers = null, \ArrayObject $securitySchemes = null, \ArrayObject $links = null, \ArrayObject $callbacks = null, \ArrayObject $pathItems = null)
     {
         if ($schemas) {
             $schemas->ksort();
@@ -42,6 +43,7 @@ public function __construct(\ArrayObject $schemas = null, \ArrayObject $response
         $this->securitySchemes = $securitySchemes;
         $this->links = $links;
         $this->callbacks = $callbacks;
+        $this->pathItems = $pathItems;
     }
 
     public function getSchemas(): ?\ArrayObject
@@ -89,6 +91,11 @@ public function getCallbacks(): ?\ArrayObject
         return $this->callbacks;
     }
 
+    public function getPathItems(): ?\ArrayObject
+    {
+        return $this->pathItems;
+    }
+
     public function withSchemas(\ArrayObject $schemas): self
     {
         $clone = clone $this;
@@ -160,4 +167,12 @@ public function withCallbacks(\ArrayObject $callbacks): self
 
         return $clone;
     }
+
+    public function withPathItems(\ArrayObject $pathItems): self
+    {
+        $clone = clone $this;
+        $clone->pathItems = $pathItems;
+
+        return $clone;
+    }
 }

src/Core/OpenApi/Model/Info.php

@@ -23,15 +23,17 @@ final class Info
     private $contact;
     private $license;
     private $version;
+    private $summary;
 
-    public function __construct(string $title, string $version, string $description = '', string $termsOfService = null, Contact $contact = null, License $license = null)
+    public function __construct(string $title, string $version, string $description = '', string $termsOfService = null, Contact $contact = null, License $license = null, string $summary = null)
     {
         $this->title = $title;
         $this->version = $version;
         $this->description = $description;
         $this->termsOfService = $termsOfService;
         $this->contact = $contact;
         $this->license = $license;
+        $this->summary = $summary;
     }
 
     public function getTitle(): string
@@ -64,6 +66,11 @@ public function getVersion(): string
         return $this->version;
     }
 
+    public function getSummary(): ?string
+    {
+        return $this->summary;
+    }
+
     public function withTitle(string $title): self
     {
         $info = clone $this;
@@ -111,4 +118,12 @@ public function withVersion(string $version): self
 
         return $clone;
     }
+
+    public function withSummary(string $summary): self
+    {
+        $clone = clone $this;
+        $clone->summary = $summary;
+
+        return $clone;
+    }
 }

src/Core/OpenApi/Model/License.php

@@ -19,11 +19,13 @@ final class License
 
     private $name;
     private $url;
+    private $identifier;
 
-    public function __construct(string $name, string $url = null)
+    public function __construct(string $name, string $url = null, string $identifier = null)
     {
         $this->name = $name;
         $this->url = $url;
+        $this->identifier = $identifier;
     }
 
     public function getName(): string
@@ -36,6 +38,11 @@ public function getUrl(): ?string
         return $this->url;
     }
 
+    public function getIdentifier(): ?string
+    {
+        return $this->identifier;
+    }
+
     public function withName(string $name): self
     {
         $clone = clone $this;
@@ -51,4 +58,12 @@ public function withUrl(?string $url): self
 
         return $clone;
     }
+
+    public function withIdentifier(?string $identifier): self
+    {
+        $clone = clone $this;
+        $clone->identifier = $identifier;
+
+        return $clone;
+    }
 }

src/Core/OpenApi/Model/Schema.php

@@ -29,9 +29,12 @@ final class Schema extends \ArrayObject
     private $deprecated;
     private $schema;
 
-    public function __construct(bool $nullable = false, $discriminator = null, bool $readOnly = false, bool $writeOnly = false, string $xml = null, $externalDocs = null, $example = null, bool $deprecated = false)
+    public function __construct(bool $nullable = null, $discriminator = null, bool $readOnly = false, bool $writeOnly = false, string $xml = null, $externalDocs = null, $example = null, bool $deprecated = false)
     {
-        $this->nullable = $nullable;
+        if (null !== $nullable) {
+            @trigger_error('The nullable keyword has been removed from the Schema Object (null can be used as a type value). This behaviour will not be possible anymore in API Platform 3.0.', \E_USER_DEPRECATED);
+            $this->nullable = $nullable;
+        }
         $this->discriminator = $discriminator;
         $this->readOnly = $readOnly;
         $this->writeOnly = $writeOnly;

src/Core/OpenApi/OpenApi.php

@@ -23,7 +23,7 @@ final class OpenApi implements DocumentationInterface
 {
     use ExtensionTrait;
 
-    public const VERSION = '3.0.3';
+    public const VERSION = '3.1.0';
 
     private $openapi;
     private $info;
@@ -33,8 +33,10 @@ final class OpenApi implements DocumentationInterface
     private $security;
     private $tags;
     private $externalDocs;
+    private $jsonSchemaDialect;
+    private $webhooks;
 
-    public function __construct(Info $info, array $servers, Paths $paths, Components $components = null, array $security = [], array $tags = [], $externalDocs = null)
+    public function __construct(Info $info, array $servers, Paths $paths, Components $components = null, array $security = [], array $tags = [], $externalDocs = null, string $jsonSchemaDialect = null, \ArrayObject $webhooks = null)
     {
         $this->openapi = self::VERSION;
         $this->info = $info;
@@ -44,6 +46,8 @@ public function __construct(Info $info, array $servers, Paths $paths, Components
         $this->security = $security;
         $this->tags = $tags;
         $this->externalDocs = $externalDocs;
+        $this->jsonSchemaDialect = $jsonSchemaDialect;
+        $this->webhooks = $webhooks;
     }
 
     public function getOpenapi(): string
@@ -86,6 +90,16 @@ public function getExternalDocs(): ?array
         return $this->externalDocs;
     }
 
+    public function getJsonSchemaDialect(): ?string
+    {
+        return $this->jsonSchemaDialect;
+    }
+
+    public function getWebhooks(): ?\ArrayObject
+    {
+        return $this->webhooks;
+    }
+
     public function withOpenapi(string $openapi): self
     {
         $clone = clone $this;
@@ -149,4 +163,12 @@ public function withExternalDocs(array $externalDocs): self
 
         return $clone;
     }
+
+    public function withJsonSchemaDialect(?string $jsonSchemaDialect): self
+    {
+        $clone = clone $this;
+        $clone->jsonSchemaDialect = $jsonSchemaDialect;
+
+        return $clone;
+    }
 }

tests/Core/OpenApi/Serializer/OpenApiNormalizerTest.php

@@ -197,6 +197,7 @@ public function testLegacyFactoryNormalize()
         $this->assertArrayNotHasKey('extensionProperties', $openApiAsArray);
         // this key is null, should not be in the output
         $this->assertArrayNotHasKey('termsOfService', $openApiAsArray['info']);
+        $this->assertArrayNotHasKey('summary', $openApiAsArray['info']);
         $this->assertArrayNotHasKey('paths', $openApiAsArray['paths']);
         $this->assertArrayHasKey('/dummies/{id}', $openApiAsArray['paths']);
         $this->assertArrayNotHasKey('servers', $openApiAsArray['paths']['/dummies/{id}']['get']);

tests/OpenApi/Model/SchemaTest.php

@@ -0,0 +1,33 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace ApiPlatform\Core\Tests\OpenApi\Model;
+
+use ApiPlatform\Core\OpenApi\Model\Schema;
+use PHPUnit\Framework\TestCase;
+use Symfony\Bridge\PhpUnit\ExpectDeprecationTrait;
+
+class SchemaTest extends TestCase
+{
+    use ExpectDeprecationTrait;
+
+    /**
+     * @group legacy
+     */
+    public function testLegacySchema()
+    {
+        $this->expectDeprecation('The nullable keyword has been removed from the Schema Object (null can be used as a type value). This behaviour will not be possible anymore in API Platform 3.0.');
+
+        $schema = new Schema(true);
+    }
+}