Skip to content

Commit e9d0139

Browse files
LoicBoursinsoyuka
LoicBoursin
and
soyuka
authored
feat(openapi): reflect specification to OpenAPI 3.1 (api-platform#4300)
* feat(openapi): update to 3.1.0 specification * test: fix phpstan error * test: use next-gen swagger-cli Co-authored-by: soyuka <[email protected]>
1 parent b2c1666 commit e9d0139

File tree

9 files changed

+124
-20
lines changed

9 files changed

+124
-20
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -309,10 +309,10 @@ jobs:
309309
tests/Fixtures/app/console api:openapi:export --spec-version=3 --yaml -o build/out/openapi/openapi_v3.yaml
310310
- name: Validate OpenAPI documents
311311
run: |
312-
npx swagger-cli validate build/out/openapi/swagger_v2.json
313-
npx swagger-cli validate build/out/openapi/swagger_v2.yaml
314-
npx swagger-cli validate build/out/openapi/openapi_v3.json
315-
npx swagger-cli validate build/out/openapi/openapi_v3.yaml
312+
npx git+https://github.com/soyuka/swagger-cli#master validate build/out/openapi/swagger_v2.json
313+
npx git+https://github.com/soyuka/swagger-cli#master validate build/out/openapi/swagger_v2.yaml
314+
npx git+https://github.com/soyuka/swagger-cli#master validate build/out/openapi/openapi_v3.json
315+
npx git+https://github.com/soyuka/swagger-cli#master validate build/out/openapi/openapi_v3.yaml
316316
- name: Upload OpenAPI artifacts
317317
if: always()
318318
uses: actions/upload-artifact@v1
@@ -875,10 +875,10 @@ jobs:
875875
tests/Fixtures/app/console api:openapi:export --spec-version=3 --yaml -o build/out/openapi/openapi_v3.yaml
876876
- name: Validate OpenAPI documents
877877
run: |
878-
npx swagger-cli validate build/out/openapi/swagger_v2.json
879-
npx swagger-cli validate build/out/openapi/swagger_v2.yaml
880-
npx swagger-cli validate build/out/openapi/openapi_v3.json
881-
npx swagger-cli validate build/out/openapi/openapi_v3.yaml
878+
npx git+https://github.com/soyuka/swagger-cli#master validate build/out/openapi/swagger_v2.json
879+
npx git+https://github.com/soyuka/swagger-cli#master validate build/out/openapi/swagger_v2.yaml
880+
npx git+https://github.com/soyuka/swagger-cli#master validate build/out/openapi/openapi_v3.json
881+
npx git+https://github.com/soyuka/swagger-cli#master validate build/out/openapi/openapi_v3.yaml
882882
- name: Upload OpenAPI artifacts
883883
if: always()
884884
uses: actions/upload-artifact@v1
@@ -1089,7 +1089,7 @@ jobs:
10891089
tests/Fixtures/app/console api:openapi:export --spec-version=3 --yaml -o build/out/openapi/openapi_v3.yaml
10901090
- name: Validate OpenAPI documents
10911091
run: |
1092-
npx swagger-cli validate build/out/openapi/swagger_v2.json
1093-
npx swagger-cli validate build/out/openapi/swagger_v2.yaml
1094-
npx swagger-cli validate build/out/openapi/openapi_v3.json
1095-
npx swagger-cli validate build/out/openapi/openapi_v3.yaml
1092+
npx git+https://github.com/soyuka/swagger-cli#master validate build/out/openapi/swagger_v2.json
1093+
npx git+https://github.com/soyuka/swagger-cli#master validate build/out/openapi/swagger_v2.yaml
1094+
npx git+https://github.com/soyuka/swagger-cli#master validate build/out/openapi/openapi_v3.json
1095+
npx git+https://github.com/soyuka/swagger-cli#master validate build/out/openapi/openapi_v3.yaml

‎features/openapi/docs.feature‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ Feature: Documentation support
1010
And the response should be in JSON
1111
And the header "Content-Type" should be equal to "application/json; charset=utf-8"
1212
# Context
13-
And the JSON node "openapi" should be equal to "3.0.3"
13+
And the JSON node "openapi" should be equal to "3.1.0"
1414
# Root properties
1515
And the JSON node "info.title" should be equal to "My Dummy API"
1616
And the JSON node "info.description" should contain "This is a test API."

‎src/Core/OpenApi/Model/Components.php‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,9 @@ final class Components
2626
private $securitySchemes;
2727
private $links;
2828
private $callbacks;
29+
private $pathItems;
2930

30-
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)
31+
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)
3132
{
3233
if ($schemas) {
3334
$schemas->ksort();
@@ -42,6 +43,7 @@ public function __construct(\ArrayObject $schemas = null, \ArrayObject $response
4243
$this->securitySchemes = $securitySchemes;
4344
$this->links = $links;
4445
$this->callbacks = $callbacks;
46+
$this->pathItems = $pathItems;
4547
}
4648

4749
public function getSchemas(): ?\ArrayObject
@@ -89,6 +91,11 @@ public function getCallbacks(): ?\ArrayObject
8991
return $this->callbacks;
9092
}
9193

94+
public function getPathItems(): ?\ArrayObject
95+
{
96+
return $this->pathItems;
97+
}
98+
9299
public function withSchemas(\ArrayObject $schemas): self
93100
{
94101
$clone = clone $this;
@@ -160,4 +167,12 @@ public function withCallbacks(\ArrayObject $callbacks): self
160167

161168
return $clone;
162169
}
170+
171+
public function withPathItems(\ArrayObject $pathItems): self
172+
{
173+
$clone = clone $this;
174+
$clone->pathItems = $pathItems;
175+
176+
return $clone;
177+
}
163178
}

‎src/Core/OpenApi/Model/Info.php‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,15 +23,17 @@ final class Info
2323
private $contact;
2424
private $license;
2525
private $version;
26+
private $summary;
2627

27-
public function __construct(string $title, string $version, string $description = '', string $termsOfService = null, Contact $contact = null, License $license = null)
28+
public function __construct(string $title, string $version, string $description = '', string $termsOfService = null, Contact $contact = null, License $license = null, string $summary = null)
2829
{
2930
$this->title = $title;
3031
$this->version = $version;
3132
$this->description = $description;
3233
$this->termsOfService = $termsOfService;
3334
$this->contact = $contact;
3435
$this->license = $license;
36+
$this->summary = $summary;
3537
}
3638

3739
public function getTitle(): string
@@ -64,6 +66,11 @@ public function getVersion(): string
6466
return $this->version;
6567
}
6668

69+
public function getSummary(): ?string
70+
{
71+
return $this->summary;
72+
}
73+
6774
public function withTitle(string $title): self
6875
{
6976
$info = clone $this;
@@ -111,4 +118,12 @@ public function withVersion(string $version): self
111118

112119
return $clone;
113120
}
121+
122+
public function withSummary(string $summary): self
123+
{
124+
$clone = clone $this;
125+
$clone->summary = $summary;
126+
127+
return $clone;
128+
}
114129
}

‎src/Core/OpenApi/Model/License.php‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,11 +19,13 @@ final class License
1919

2020
private $name;
2121
private $url;
22+
private $identifier;
2223

23-
public function __construct(string $name, string $url = null)
24+
public function __construct(string $name, string $url = null, string $identifier = null)
2425
{
2526
$this->name = $name;
2627
$this->url = $url;
28+
$this->identifier = $identifier;
2729
}
2830

2931
public function getName(): string
@@ -36,6 +38,11 @@ public function getUrl(): ?string
3638
return $this->url;
3739
}
3840

41+
public function getIdentifier(): ?string
42+
{
43+
return $this->identifier;
44+
}
45+
3946
public function withName(string $name): self
4047
{
4148
$clone = clone $this;
@@ -51,4 +58,12 @@ public function withUrl(?string $url): self
5158

5259
return $clone;
5360
}
61+
62+
public function withIdentifier(?string $identifier): self
63+
{
64+
$clone = clone $this;
65+
$clone->identifier = $identifier;
66+
67+
return $clone;
68+
}
5469
}

‎src/Core/OpenApi/Model/Schema.php‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,9 +29,12 @@ final class Schema extends \ArrayObject
2929
private $deprecated;
3030
private $schema;
3131

32-
public function __construct(bool $nullable = false, $discriminator = null, bool $readOnly = false, bool $writeOnly = false, string $xml = null, $externalDocs = null, $example = null, bool $deprecated = false)
32+
public function __construct(bool $nullable = null, $discriminator = null, bool $readOnly = false, bool $writeOnly = false, string $xml = null, $externalDocs = null, $example = null, bool $deprecated = false)
3333
{
34-
$this->nullable = $nullable;
34+
if (null !== $nullable) {
35+
@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);
36+
$this->nullable = $nullable;
37+
}
3538
$this->discriminator = $discriminator;
3639
$this->readOnly = $readOnly;
3740
$this->writeOnly = $writeOnly;

‎src/Core/OpenApi/OpenApi.php‎

Lines changed: 24 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ final class OpenApi implements DocumentationInterface
2323
{
2424
use ExtensionTrait;
2525

26-
public const VERSION = '3.0.3';
26+
public const VERSION = '3.1.0';
2727

2828
private $openapi;
2929
private $info;
@@ -33,8 +33,10 @@ final class OpenApi implements DocumentationInterface
3333
private $security;
3434
private $tags;
3535
private $externalDocs;
36+
private $jsonSchemaDialect;
37+
private $webhooks;
3638

37-
public function __construct(Info $info, array $servers, Paths $paths, Components $components = null, array $security = [], array $tags = [], $externalDocs = null)
39+
public function __construct(Info $info, array $servers, Paths $paths, Components $components = null, array $security = [], array $tags = [], $externalDocs = null, string $jsonSchemaDialect = null, \ArrayObject $webhooks = null)
3840
{
3941
$this->openapi = self::VERSION;
4042
$this->info = $info;
@@ -44,6 +46,8 @@ public function __construct(Info $info, array $servers, Paths $paths, Components
4446
$this->security = $security;
4547
$this->tags = $tags;
4648
$this->externalDocs = $externalDocs;
49+
$this->jsonSchemaDialect = $jsonSchemaDialect;
50+
$this->webhooks = $webhooks;
4751
}
4852

4953
public function getOpenapi(): string
@@ -86,6 +90,16 @@ public function getExternalDocs(): ?array
8690
return $this->externalDocs;
8791
}
8892

93+
public function getJsonSchemaDialect(): ?string
94+
{
95+
return $this->jsonSchemaDialect;
96+
}
97+
98+
public function getWebhooks(): ?\ArrayObject
99+
{
100+
return $this->webhooks;
101+
}
102+
89103
public function withOpenapi(string $openapi): self
90104
{
91105
$clone = clone $this;
@@ -149,4 +163,12 @@ public function withExternalDocs(array $externalDocs): self
149163

150164
return $clone;
151165
}
166+
167+
public function withJsonSchemaDialect(?string $jsonSchemaDialect): self
168+
{
169+
$clone = clone $this;
170+
$clone->jsonSchemaDialect = $jsonSchemaDialect;
171+
172+
return $clone;
173+
}
152174
}

‎tests/Core/OpenApi/Serializer/OpenApiNormalizerTest.php‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -197,6 +197,7 @@ public function testLegacyFactoryNormalize()
197197
$this->assertArrayNotHasKey('extensionProperties', $openApiAsArray);
198198
// this key is null, should not be in the output
199199
$this->assertArrayNotHasKey('termsOfService', $openApiAsArray['info']);
200+
$this->assertArrayNotHasKey('summary', $openApiAsArray['info']);
200201
$this->assertArrayNotHasKey('paths', $openApiAsArray['paths']);
201202
$this->assertArrayHasKey('/dummies/{id}', $openApiAsArray['paths']);
202203
$this->assertArrayNotHasKey('servers', $openApiAsArray['paths']['/dummies/{id}']['get']);

‎tests/OpenApi/Model/SchemaTest.php‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
<?php
2+
3+
/*
4+
* This file is part of the API Platform project.
5+
*
6+
* (c) Kévin Dunglas <[email protected]>
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*/
11+
12+
declare(strict_types=1);
13+
14+
namespace ApiPlatform\Core\Tests\OpenApi\Model;
15+
16+
use ApiPlatform\Core\OpenApi\Model\Schema;
17+
use PHPUnit\Framework\TestCase;
18+
use Symfony\Bridge\PhpUnit\ExpectDeprecationTrait;
19+
20+
class SchemaTest extends TestCase
21+
{
22+
use ExpectDeprecationTrait;
23+
24+
/**
25+
* @group legacy
26+
*/
27+
public function testLegacySchema()
28+
{
29+
$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.');
30+
31+
$schema = new Schema(true);
32+
}
33+
}

0 commit comments

Comments
 (0)