Skip to content

Commit 0e097f4

Browse files
gaiaz-iusipovgaiaz-iusipov
committed
[org.openapis.v3] Support for OpenAPI Extensions apple#48 
1 parent fa1f4ad commit 0e097f4

File tree

10 files changed

+172
-34
lines changed

10 files changed

+172
-34
lines changed

‎packages/org.openapis.v3.contrib/PklProject

+1-1
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
amends "../basePklProject.pkl"
1717

1818
package {
19-
version = "1.0.5"
19+
version = "1.1.0"
2020
}
2121

2222
dependencies {

‎packages/org.openapis.v3.contrib/PklProject.deps.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
"resolvedDependencies": {
44
"package://pkg.pkl-lang.org/pkl-pantry/org.openapis.v3@2": {
55
"type": "local",
6-
"uri": "projectpackage://pkg.pkl-lang.org/pkl-pantry/org.openapis.v3@2.1.3",
6+
"uri": "projectpackage://pkg.pkl-lang.org/pkl-pantry/org.openapis.v3@2.2.0",
77
"path": "../org.openapis.v3"
88
}
99
}

‎packages/org.openapis.v3/Document.pkl

+17-18
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
//===----------------------------------------------------------------------===//
2-
// Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.
2+
// Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
33
//
44
// Licensed under the Apache License, Version 2.0 (the "License");
55
// you may not use this file except in compliance with the License.
@@ -15,15 +15,15 @@
1515
//===----------------------------------------------------------------------===//
1616
open module org.openapis.v3.Document
1717

18+
import "Components.pkl"
19+
import "Extension.pkl"
20+
import "ExternalDocs.pkl"
1821
import "Info.pkl"
19-
import "Server.pkl"
2022
import "PathItem.pkl"
21-
import "Components.pkl"
23+
import "Reference.pkl" as _Reference
2224
import "Security.pkl"
25+
import "Server.pkl"
2326
import "Tag.pkl"
24-
import "ExternalDocs.pkl"
25-
import "Reference.pkl" as _Reference
26-
import "HTTPResponse.pkl" as _HttpResponse
2727

2828
/// This string MUST be the semantic version number of the OpenAPI Specification version that the OpenAPI document
2929
/// uses.
@@ -82,17 +82,16 @@ externalDocs: ExternalDocs?
8282
// re-export types so they are available without import
8383
typealias Reference = _Reference
8484

85-
// noinspection TypeMismatch
86-
/// The output format to render.
87-
///
88-
/// OpenAPI documents can be defined in either JSON or YAML.
89-
/// This is a Pkl-only property that is excluded from OpenAPI output.
90-
hidden __format__: "json"|"yaml" = read?("prop:pkl.outputFormat") ?? "json"
91-
9285
output {
93-
renderer =
94-
if (__format__ == "json")
95-
new JsonRenderer {}
96-
else
97-
new YamlRenderer {}
86+
// noinspection TypeMismatch
87+
local const format: "json"|"yaml" = read?("prop:pkl.outputFormat") ?? "json"
88+
89+
local const renderers: Mapping<String, ValueRenderer> = new {
90+
["json"] = new JsonRenderer {}
91+
["yaml"] = new YamlRenderer {}
92+
}
93+
94+
renderer = (renderers[format]) {
95+
converters = Extension.converters
96+
}
9897
}

‎packages/org.openapis.v3/Extension.pkl

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
//===----------------------------------------------------------------------===//
2+
// Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
3+
//
4+
// Licensed under the Apache License, Version 2.0 (the "License");
5+
// you may not use this file except in compliance with the License.
6+
// You may obtain a copy of the License at
7+
//
8+
// https://www.apache.org/licenses/LICENSE-2.0
9+
//
10+
// Unless required by applicable law or agreed to in writing, software
11+
// distributed under the License is distributed on an "AS IS" BASIS,
12+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
// See the License for the specific language governing permissions and
14+
// limitations under the License.
15+
//===----------------------------------------------------------------------===//
16+
/// The Extension object represents the possibility of adding additional data
17+
/// to extend the specification at certain points.
18+
///
19+
/// <https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specification-extensions>
20+
module org.openapis.v3.Extension
21+
22+
import "Info.pkl"
23+
import "SecurityScheme.pkl"
24+
import "Schema.pkl"
25+
26+
/// A string representing the key of an extension.
27+
typealias Key = String(startsWith("x-"), length > 2)
28+
29+
hidden converters: Mapping<Class|String, (unknown) -> Any> = new {
30+
local extractExtensions = (it: Module) -> it.toMap() + (it.getProperty("extensions") ?? Map()).toMap()
31+
[Schema.getClass()] = extractExtensions
32+
[SecurityScheme.getClass()] = extractExtensions
33+
[Info.getClass()] = extractExtensions
34+
}

‎packages/org.openapis.v3/Info.pkl

+11-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
//===----------------------------------------------------------------------===//
2-
// Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.
2+
// Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
33
//
44
// Licensed under the Apache License, Version 2.0 (the "License");
55
// you may not use this file except in compliance with the License.
@@ -19,6 +19,7 @@
1919
/// tools for convenience.
2020
module org.openapis.v3.Info
2121

22+
import "Extension.pkl"
2223
import "Contact.pkl"
2324
import "License.pkl"
2425

@@ -45,3 +46,12 @@ contact: Contact?
4546

4647
/// The license information for the exposed API.
4748
license: License?
49+
50+
/// Custom properties starting with x- extend OpenAPI with additional information
51+
/// or functionality.
52+
///
53+
/// This is a child property because Pkl modules cannot express both known names
54+
/// and arbitrary names.
55+
///
56+
/// <https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specification-extensions>
57+
hidden extensions: Mapping<Extension.Key, Any>?

‎packages/org.openapis.v3/PklProject

+1-1
Original file line numberDiff line numberDiff line change
@@ -17,5 +17,5 @@
1717
amends "../basePklProject.pkl"
1818

1919
package {
20-
version = "2.1.3"
20+
version = "2.2.0"
2121
}

‎packages/org.openapis.v3/Schema.pkl

+24-12
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
//===----------------------------------------------------------------------===//
2-
// Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.
2+
// Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
33
//
44
// Licensed under the Apache License, Version 2.0 (the "License");
55
// you may not use this file except in compliance with the License.
@@ -31,8 +31,9 @@
3131
/// <https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#schema-object>
3232
open module org.openapis.v3.Schema
3333

34-
import "Schema.pkl"
34+
import "Extension.pkl"
3535
import "Reference.pkl"
36+
import "Schema.pkl"
3637

3738
/// The basic type of the value represented by this schema.
3839
///
@@ -291,6 +292,15 @@ deprecated: Boolean?
291292
/// value can be used to contain the example with escaping where necessary.
292293
example: Any?
293294

295+
/// Custom properties starting with x- extend OpenAPI with additional information
296+
/// or functionality.
297+
///
298+
/// This is a child property because Pkl modules cannot express both known names
299+
/// and arbitrary names.
300+
///
301+
/// <https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specification-extensions>
302+
hidden extensions: Mapping<Extension.Key, Any>?
303+
294304
/// Helps inform of alternative schemas.
295305
///
296306
/// When request bodies or response payloads may be one of a number of different
@@ -367,16 +377,18 @@ class PropertySchema extends Schema {
367377
xml: Xml?
368378
}
369379

370-
hidden renderers: Mapping<String, ValueRenderer> = new {
371-
["json"] = new JsonRenderer {}
372-
["yaml"] = new YamlRenderer {}
373-
["pcf"] = new PcfRenderer {}
374-
}
375-
376380
output {
377381
// It's pretty common to have OpenAPI written in YAML. Therefore, we support the YAML format too.
378-
renderer = let (format = read?("prop:pkl.outputFormat") ?? "json")
379-
if (renderers.containsKey(format))
380-
renderers[format]
381-
else throw("Unsupported output format: `\(format)`. Supported formats are `json`, `yaml` and `pcf`.")
382+
// noinspection TypeMismatch
383+
local const format: "json"|"yaml"|"pcf" = read?("prop:pkl.outputFormat") ?? "json"
384+
385+
local const renderers: Mapping<String, ValueRenderer> = new {
386+
["json"] = new JsonRenderer {}
387+
["yaml"] = new YamlRenderer {}
388+
["pcf"] = new PcfRenderer {}
389+
}
390+
391+
renderer = (renderers[format]) {
392+
converters = Extension.converters
393+
}
382394
}

‎packages/org.openapis.v3/SecurityScheme.pkl

+10
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
/// Contact information for the exposed API.
1717
module org.openapis.v3.SecurityScheme
1818

19+
import "Extension.pkl"
1920
import "OAuthFlows.pkl"
2021

2122
typealias SecuritySchemeType = "apiKey"|"http"|"oauth2"|"openIdConnect"
@@ -51,3 +52,12 @@ flows: OAuthFlows?((type == "oauth2").implies(this != null))
5152
///
5253
/// This MUST be in the form of a URL.
5354
openIdConnectUrl: Uri?((type == "openIdConnect").implies(this != null))
55+
56+
/// Custom properties starting with x- extend OpenAPI with additional information
57+
/// or functionality.
58+
///
59+
/// This is a child property because Pkl modules cannot express both known names
60+
/// and arbitrary names.
61+
///
62+
/// <https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specification-extensions>
63+
hidden extensions: Mapping<Extension.Key, Any>?

‎packages/org.openapis.v3/examples/extension-example.pkl

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
//===----------------------------------------------------------------------===//
2+
// Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
3+
//
4+
// Licensed under the Apache License, Version 2.0 (the "License");
5+
// you may not use this file except in compliance with the License.
6+
// You may obtain a copy of the License at
7+
//
8+
// https://www.apache.org/licenses/LICENSE-2.0
9+
//
10+
// Unless required by applicable law or agreed to in writing, software
11+
// distributed under the License is distributed on an "AS IS" BASIS,
12+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
// See the License for the specific language governing permissions and
14+
// limitations under the License.
15+
//===----------------------------------------------------------------------===//
16+
amends "../Document.pkl"
17+
18+
info {
19+
title = "Extension Example"
20+
version = "1.0.0"
21+
extensions {
22+
["x-key"] = "info"
23+
}
24+
}
25+
26+
components {
27+
schemas {
28+
["Schema"] {
29+
type = "string"
30+
extensions {
31+
["x-key"] = "schema"
32+
}
33+
}
34+
}
35+
securitySchemes {
36+
["basicAuth"] {
37+
type = "http"
38+
scheme = "basic"
39+
extensions {
40+
["x-key"] = "basicAuth"
41+
}
42+
}
43+
}
44+
}

‎packages/org.openapis.v3/tests/Document.pkl-expected.pcf

+29
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,33 @@
11
examples {
2+
["extension-example"] {
3+
"""
4+
{
5+
"openapi": "3.0.3",
6+
"info": {
7+
"title": "Extension Example",
8+
"version": "1.0.0",
9+
"x-key": "info"
10+
},
11+
"paths": {},
12+
"components": {
13+
"schemas": {
14+
"Schema": {
15+
"type": "string",
16+
"x-key": "schema"
17+
}
18+
},
19+
"securitySchemes": {
20+
"basicAuth": {
21+
"type": "http",
22+
"scheme": "basic",
23+
"x-key": "basicAuth"
24+
}
25+
}
26+
}
27+
}
28+
29+
"""
30+
}
231
["link-example"] {
332
"""
433
{

0 commit comments

Comments
 (0)