Skip to content

Commit 0dfd872

Browse files
DmitryAnanskyDmitryAnansky
committed
feat: update oas 3.1 and async2 node types
1 parent 53ec1ef commit 0dfd872

2 files changed

Lines changed: 126 additions & 42 deletions

File tree

‎packages/core/src/types/asyncapi2.ts‎

Lines changed: 88 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,10 @@ const Root: NodeType = {
1313
properties: {
1414
asyncapi: null, // TODO: validate semver format and supported version
1515
info: 'Info',
16-
id: { type: 'string' },
16+
id: {
17+
type: 'string',
18+
description: 'Identifier of the application the AsyncAPI document is defining.',
19+
},
1720
servers: 'ServerMap',
1821
channels: 'ChannelMap',
1922
components: 'Components',
@@ -22,17 +25,29 @@ const Root: NodeType = {
2225
defaultContentType: { type: 'string' },
2326
},
2427
required: ['asyncapi', 'channels', 'info'],
28+
documentationLink: 'https://v2.asyncapi.com/docs/reference/specification/v2.0.0',
2529
};
2630

2731
const Channel: NodeType = {
2832
properties: {
29-
description: { type: 'string' },
33+
description: {
34+
type: 'string',
35+
description:
36+
'An optional description of this channel item. CommonMark syntax can be used for rich text representation.',
37+
},
3038
subscribe: 'Operation',
3139
publish: 'Operation',
3240
parameters: 'ParametersMap',
3341
bindings: 'ChannelBindings',
34-
servers: { type: 'array', items: { type: 'string' } },
42+
servers: {
43+
type: 'array',
44+
items: { type: 'string' },
45+
description:
46+
'The servers on which this channel is available, specified as an optional unordered list of names (string keys) of Server Objects defined in the Servers Object (a map).',
47+
},
3548
},
49+
description: 'Describes the operations available on a single channel.',
50+
documentationLink: 'https://v2.asyncapi.com/docs/concepts/channel',
3651
};
3752

3853
const ChannelMap: NodeType = {
@@ -67,28 +82,52 @@ const ChannelBindings: NodeType = {
6782
];
6883
},
6984
additionalProperties: { type: 'object' },
85+
documentationLink:
86+
'https://v2.asyncapi.com/docs/reference/specification/v2.6.0#channelBindingsObject',
87+
description: 'Map describing protocol-specific definitions for a channel.',
7088
};
7189

7290
export const Tag: NodeType = {
7391
properties: {
74-
name: { type: 'string' },
75-
description: { type: 'string' },
92+
name: { type: 'string', description: 'REQUIRED. The name of the tag.' },
93+
description: {
94+
type: 'string',
95+
description:
96+
'A short description for the tag. CommonMark syntax can be used for rich text representation.',
97+
},
7698
externalDocs: 'ExternalDocs',
7799
},
78100
required: ['name'],
101+
description: 'Allows adding meta data to a single tag.',
102+
documentationLink: 'https://v2.asyncapi.com/docs/reference/specification/v2.6.0#tagObject',
79103
};
80104

81105
export const ExternalDocs: NodeType = {
82106
properties: {
83-
description: { type: 'string' },
84-
url: { type: 'string' },
107+
description: {
108+
type: 'string',
109+
description:
110+
'A short description of the target documentation. CommonMark syntax can be used for rich text representation.',
111+
},
112+
url: {
113+
type: 'string',
114+
description:
115+
'REQUIRED. The URL for the target documentation. This MUST be in the form of an absolute URL.',
116+
},
85117
},
86118
required: ['url'],
119+
documentationLink:
120+
'https://v2.asyncapi.com/docs/reference/specification/v2.6.0#externalDocumentationObject',
121+
description: 'Allows referencing an external resource for extended documentation.',
87122
};
88123

89124
const SecurityRequirement: NodeType = {
90125
properties: {},
91126
additionalProperties: { type: 'array', items: { type: 'string' } },
127+
documentationLink:
128+
'https://v2.asyncapi.com/docs/reference/specification/v2.6.0#securityRequirementObject',
129+
description:
130+
'Lists the required security schemes to execute this operation. The name used for each property MUST correspond to a security scheme declared in the Security Schemes under the Components Object.',
92131
};
93132

94133
const ServerBindings: NodeType = {
@@ -118,20 +157,42 @@ const ServerBindings: NodeType = {
118157
];
119158
},
120159
additionalProperties: { type: 'object' },
160+
documentationLink:
161+
'https://v2.asyncapi.com/docs/reference/specification/v2.6.0#serverBindingsObject',
162+
description: 'Map describing protocol-specific definitions for a server.',
121163
};
122164

123165
const Server: NodeType = {
124166
properties: {
125-
url: { type: 'string' },
126-
protocol: { type: 'string' },
127-
protocolVersion: { type: 'string' },
128-
description: { type: 'string' },
167+
url: {
168+
type: 'string',
169+
description:
170+
'REQUIRED. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the AsyncAPI document is being served. Variable substitutions will be made when a variable is named in {braces}.',
171+
},
172+
protocol: {
173+
type: 'string',
174+
description:
175+
'REQUIRED. The protocol this URL supports for connection. Supported protocol include, but are not limited to: amqp, amqps, http, https, ibmmq, jms, kafka, kafka-secure, anypointmq, mqtt, secure-mqtt, solace, stomp, stomps, ws, wss, mercure, googlepubsub, pulsar.',
176+
},
177+
protocolVersion: {
178+
type: 'string',
179+
description:
180+
'The version of the protocol used for connection. For instance: AMQP 0.9.1, HTTP 2.0, Kafka 1.0.0, etc.',
181+
},
182+
description: {
183+
type: 'string',
184+
description:
185+
'An optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation.',
186+
},
129187
variables: 'ServerVariablesMap',
130188
security: 'SecurityRequirementList',
131189
bindings: 'ServerBindings',
132190
tags: 'TagList',
133191
},
134192
required: ['url', 'protocol'],
193+
documentationLink: 'https://v2.asyncapi.com/docs/reference/specification/v2.6.0#serverObject',
194+
description:
195+
'An object representing a message broker, a server or any other kind of computer program capable of sending and/or receiving data. This object is used to capture details such as URIs, protocols and security configuration. Variable substitution can be used so that some details, for example usernames and passwords, can be injected by code generation tools.',
135196
};
136197

137198
export const ServerMap: NodeType = {
@@ -146,15 +207,29 @@ export const ServerVariable: NodeType = {
146207
enum: {
147208
type: 'array',
148209
items: { type: 'string' },
210+
description:
211+
'An enumeration of string values to be used if the substitution options are from a limited set.',
212+
},
213+
default: {
214+
type: 'string',
215+
description:
216+
'The default value to use for substitution, and to send, if an alternate value is not supplied.',
217+
},
218+
description: {
219+
type: 'string',
220+
description:
221+
'An optional description for the server variable. CommonMark syntax MAY be used for rich text representation.',
149222
},
150-
default: { type: 'string' },
151-
description: { type: 'string' },
152223
examples: {
153224
type: 'array',
154225
items: { type: 'string' },
226+
description: 'An array of examples of the server variable.',
155227
},
156228
},
157229
required: [],
230+
documentationLink:
231+
'https://v2.asyncapi.com/docs/reference/specification/v2.6.0#serverVariableObject',
232+
description: 'An object representing a Server Variable for server URL template substitution.',
158233
};
159234

160235
const Info: NodeType = {

‎packages/core/src/types/oas3_1.ts‎

Lines changed: 38 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -12,70 +12,79 @@ const Root: NodeType = {
1212
paths: 'Paths',
1313
webhooks: 'WebhooksMap',
1414
components: 'Components',
15-
jsonSchemaDialect: { type: 'string' },
15+
jsonSchemaDialect: {
16+
type: 'string',
17+
description:
18+
'The default value for the $schema keyword within Schema Objects contained within this OAS document. This MUST be in the form of a URI.',
19+
},
1620
},
1721
required: ['openapi', 'info'],
1822
requiredOneOf: ['paths', 'components', 'webhooks'],
1923
extensionsPrefix: 'x-',
24+
documentationLink: 'https://redocly.com/learn/openapi/openapi-visual-reference/openapi#openapi',
25+
description:
26+
'REQUIRED. This string MUST be the semantic version number of the OpenAPI Specification version that the OpenAPI document uses. The openapi field SHOULD be used by tooling specifications and clients to interpret the OpenAPI document. This is not related to the API info.version string.',
2027
};
2128

2229
const License: NodeType = {
30+
...Oas3Types.License,
2331
properties: {
24-
name: { type: 'string' },
25-
url: { type: 'string' },
26-
identifier: { type: 'string' },
32+
...Oas3Types.License.properties,
33+
identifier: {
34+
type: 'string',
35+
description:
36+
'An [SPDX-Licenses] expression for the API. The identifier field is mutually exclusive of the url field.',
37+
},
2738
},
28-
required: ['name'],
29-
extensionsPrefix: 'x-',
3039
};
3140

3241
const Info: NodeType = {
42+
...Oas3Types.Info,
3343
properties: {
34-
title: { type: 'string' },
35-
version: { type: 'string' },
36-
description: { type: 'string' },
37-
termsOfService: { type: 'string' },
38-
summary: { type: 'string' },
39-
contact: 'Contact',
40-
license: 'License',
41-
'x-logo': 'Logo',
44+
...Oas3Types.Info.properties,
45+
summary: {
46+
type: 'string',
47+
description: 'A short summary of the API. This field MAY be used by tooling as required.',
48+
},
4249
},
43-
required: ['title', 'version'],
44-
extensionsPrefix: 'x-',
4550
};
4651

4752
const Components: NodeType = {
53+
...Oas3Types.Components,
4854
properties: {
49-
parameters: 'NamedParameters',
50-
schemas: 'NamedSchemas',
51-
responses: 'NamedResponses',
52-
examples: 'NamedExamples',
53-
requestBodies: 'NamedRequestBodies',
54-
headers: 'NamedHeaders',
55-
securitySchemes: 'NamedSecuritySchemes',
56-
links: 'NamedLinks',
57-
callbacks: 'NamedCallbacks',
55+
...Oas3Types.Components.properties,
5856
pathItems: 'NamedPathItems',
5957
},
60-
extensionsPrefix: 'x-',
6158
};
6259

6360
const Operation: NodeType = {
6461
properties: {
6562
tags: {
6663
type: 'array',
6764
items: { type: 'string' },
65+
description:
66+
'A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.',
6867
},
6968
summary: {
7069
type: 'string',
71-
description: `Optional short summary of what the operation does.`,
70+
description: 'A short summary of what the operation does.',
71+
documentationLink:
72+
'https://redocly.com/learn/openapi/openapi-visual-reference/operation#summary',
7273
},
7374
description: {
7475
type: 'string',
75-
description: `Optional description of the operation and its behavior. Supports Markdown formatting. Redocly tools support using $ref in this field to reuse or include content from other sources.`,
76+
description: 'A verbose explanation of the operation behavior.',
77+
documentationLink:
78+
'https://redocly.com/learn/openapi/openapi-visual-reference/operation#description',
7679
},
7780
externalDocs: 'ExternalDocs',
78-
operationId: { type: 'string' },
81+
operationId: {
82+
type: 'string',
83+
description:
84+
'The operationId is path segment or path fragment in deep links to a specific operation.',
85+
documentationLink:
86+
'https://redocly.com/learn/openapi/openapi-visual-reference/operation#operationid',
87+
},
7988
parameters: 'ParameterList',
8089
security: 'SecurityRequirementList',
8190
servers: 'ServerList',

0 commit comments

Comments
 (0)