refactor(ls): scope OpenAPI 3.x.y rules explicitly (batch 1) (#3494)

Includes: - Callback Object - Components Object - Contact Object - content meta class - Discriminator Object - Encoding Object Refs #3478
swagger-api · Dec 4, 2023 · 81b8891 · 81b8891
1 parent fce4096
commit 81b8891
Show file tree

Hide file tree

Showing 43 changed files with 218 additions and 248 deletions.
diff --git a/packages/apidom-ls/src/config/openapi/callback/completion.ts b/packages/apidom-ls/src/config/openapi/callback/completion.ts
@@ -3,6 +3,7 @@ import {
   CompletionFormat,
   CompletionType,
 } from '../../../apidom-language-types';
+import { OpenAPI3 } from '../target-specs';
 
 const completion: ApidomCompletionItem[] = [
   {
@@ -16,6 +17,7 @@ const completion: ApidomCompletionItem[] = [
       kind: 'markdown',
       value: 'A reference to a Callback.',
     },
+    targetSpecs: OpenAPI3,
   },
   {
     label: '$url',
@@ -28,6 +30,7 @@ const completion: ApidomCompletionItem[] = [
       kind: 'markdown',
       value: 'Request URL',
     },
+    targetSpecs: OpenAPI3,
   },
   {
     label: '$method',
@@ -40,6 +43,7 @@ const completion: ApidomCompletionItem[] = [
       kind: 'markdown',
       value: 'HTTP Method',
     },
+    targetSpecs: OpenAPI3,
   },
   {
     label: '$statusCode',
@@ -52,6 +56,7 @@ const completion: ApidomCompletionItem[] = [
       kind: 'markdown',
       value: 'Status Code',
     },
+    targetSpecs: OpenAPI3,
   },
   {
     label: '$request.path...',
@@ -64,6 +69,7 @@ const completion: ApidomCompletionItem[] = [
       kind: 'markdown',
       value: 'Request Path',
     },
+    targetSpecs: OpenAPI3,
   },
   {
     label: '$request.query...',
@@ -76,6 +82,7 @@ const completion: ApidomCompletionItem[] = [
       kind: 'markdown',
       value: 'Request Query',
     },
+    targetSpecs: OpenAPI3,
   },
   {
     label: '$request.header...',
@@ -88,6 +95,7 @@ const completion: ApidomCompletionItem[] = [
       kind: 'markdown',
       value: 'Request Header',
     },
+    targetSpecs: OpenAPI3,
   },
   {
     label: '$request.header...',
@@ -100,6 +108,7 @@ const completion: ApidomCompletionItem[] = [
       kind: 'markdown',
       value: 'Request Header',
     },
+    targetSpecs: OpenAPI3,
   },
   {
     label: '$request.body',
@@ -112,6 +121,7 @@ const completion: ApidomCompletionItem[] = [
       kind: 'markdown',
       value: 'Request Body',
     },
+    targetSpecs: OpenAPI3,
   },
   {
     label: '$request.body#/...',
@@ -124,6 +134,7 @@ const completion: ApidomCompletionItem[] = [
       kind: 'markdown',
       value: 'Request Body..',
     },
+    targetSpecs: OpenAPI3,
   },
   {
     label: '$response.path...',
@@ -136,6 +147,7 @@ const completion: ApidomCompletionItem[] = [
       kind: 'markdown',
       value: 'Response Path',
     },
+    targetSpecs: OpenAPI3,
   },
   {
     label: '$response.query...',
@@ -148,6 +160,7 @@ const completion: ApidomCompletionItem[] = [
       kind: 'markdown',
       value: 'Response Query',
     },
+    targetSpecs: OpenAPI3,
   },
   {
     label: '$response.header...',
@@ -160,6 +173,7 @@ const completion: ApidomCompletionItem[] = [
       kind: 'markdown',
       value: 'Response Header',
     },
+    targetSpecs: OpenAPI3,
   },
   {
     label: '$response.header...',
@@ -172,6 +186,7 @@ const completion: ApidomCompletionItem[] = [
       kind: 'markdown',
       value: 'Response Header',
     },
+    targetSpecs: OpenAPI3,
   },
   {
     label: '$response.body',
@@ -184,6 +199,7 @@ const completion: ApidomCompletionItem[] = [
       kind: 'markdown',
       value: 'Response Body',
     },
+    targetSpecs: OpenAPI3,
   },
   {
     label: '$response.body#/...',
@@ -196,6 +212,7 @@ const completion: ApidomCompletionItem[] = [
       kind: 'markdown',
       value: 'Response Body..',
     },
+    targetSpecs: OpenAPI3,
   },
 ];
 

diff --git a/packages/apidom-ls/src/config/openapi/callback/documentation.ts b/packages/apidom-ls/src/config/openapi/callback/documentation.ts
@@ -1,16 +1,13 @@
+import { OpenAPI30, OpenAPI31 } from '../target-specs';
+
 const documentation = [
   {
     docs: "#### [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#callbackObject)\n\nA map of possible out-of band callbacks related to the parent operation.\nEach value in the map is a [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#pathItemObject) that describes a set of requests that may be initiated by the API provider and the expected responses.\nThe key value used to identify the path item object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation.\n\n##### Patterned Fields\nField Pattern | Type | Description\n---|:---:|---\n{expression} | [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#pathItemObject) | A Path Item Object used to define a callback request and expected responses.  A [complete example](https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.0/callback-example.yaml) is available.\n\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specificationExtensions).\n\n##### Key Expression\n\nThe key that identifies the [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#pathItemObject) is a [runtime expression](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#runtimeExpression) that can be evaluated in the context of a runtime HTTP request/response to identify the URL to be used for the callback request.\nA simple example might be `$request.body#/url`.\nHowever, using a [runtime expression](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#runtimeExpression) the complete HTTP message can be accessed.\nThis includes accessing any part of a body that a JSON Pointer [RFC6901](https://tools.ietf.org/html/rfc6901) can reference.\n\nFor example, given the following HTTP request:\n\n```http\nPOST /subscribe/myevent?queryUrl=http://clientdomain.com/stillrunning HTTP/1.1\nHost: example.org\nContent-Type: application/json\nContent-Length: 187\n\n{\n  \"failedUrl\" : \"http://clientdomain.com/failed\",\n  \"successUrls\" : [\n    \"http://clientdomain.com/fast\",\n    \"http://clientdomain.com/medium\",\n    \"http://clientdomain.com/slow\"\n  ]\n}\n\n201 Created\nLocation: http://example.org/subscription/1\n```\n\nThe following examples show how the various expressions evaluate, assuming the callback operation has a path parameter named `eventType` and a query parameter named `queryUrl`.\n\nExpression | Value\n---|:---\n$url | http://example.org/subscribe/myevent?queryUrl=http://clientdomain.com/stillrunning\n$method | POST\n$request.path.eventType | myevent\n$request.query.queryUrl | http://clientdomain.com/stillrunning\n$request.header.content-Type | application/json\n$request.body#/failedUrl | http://clientdomain.com/failed\n$request.body#/successUrls/2 | http://clientdomain.com/medium\n$response.header.Location | http://example.org/subscription/1\n\n\n##### Callback Object Examples\n\nThe following example uses the user provided `queryUrl` query string parameter to define the callback URL.  This is an example of how to use a callback object to describe a WebHook callback that goes with the subscription operation to enable registering for the WebHook.\n\n\n\\\nYAML\n```yaml\nmyCallback:\n  '{$request.query.queryUrl}':\n    post:\n      requestBody:\n        description: Callback payload\n        content:\n          'application/json':\n            schema:\n              $ref: '#/components/schemas/SomePayload'\n      responses:\n        '200':\n          description: callback successfully processed\n```\n\nThe following example shows a callback where the server is hard-coded, but the query string parameters are populated from the `id` and `email` property in the request body.\n\n```yaml\ntransactionCallback:\n  'http://notificationServer.com?transactionId={$request.body#/id}&email={$request.body#/email}':\n    post:\n      requestBody:\n        description: Callback payload\n        content:\n          'application/json':\n            schema:\n              $ref: '#/components/schemas/SomePayload'\n      responses:\n        '200':\n          description: callback successfully processed\n```",
-    targetSpecs: [
-      { namespace: 'openapi', version: '3.0.0' },
-      { namespace: 'openapi', version: '3.0.1' },
-      { namespace: 'openapi', version: '3.0.2' },
-      { namespace: 'openapi', version: '3.0.3' },
-    ],
+    targetSpecs: OpenAPI30,
   },
   {
     docs: "#### [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callback-object)\n\nA map of possible out-of band callbacks related to the parent operation. Each value in the map is a [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject) that describes a set of requests that may be initiated by the API provider and the expected responses. The key value used to identify the path item object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation.\n\n\\\nTo describe incoming requests from the API provider independent from another API call, use the [`webhooks`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasWebhooks) field.\n\n##### Patterned Fields\n\nField Pattern | Type | Description\n---|:---:|---\n{expression} | [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) | A Path Item Object, or a reference to one, used to define a callback request and expected responses. A [complete example](https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.0/callback-example.yaml) is available.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Key Expression\n\nThe key that identifies the [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject) is a [runtime expression](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#runtimeExpression) that can be evaluated in the context of a runtime HTTP request/response to identify the URL to be used for the callback request. A simple example might be `$request.body#/url`. However, using a [runtime expression](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#runtimeExpression) the complete HTTP message can be accessed. This includes accessing any part of a body that a JSON Pointer [RFC6901](https://tools.ietf.org/html/rfc6901) can reference.\n\n\\\nFor example, given the following HTTP request:\n\n\\\nYAML\n```yaml\nPOST /subscribe/myevent?queryUrl=https://clientdomain.com/stillrunning HTTP/1.1\nHost: example.org\nContent-Type: application/json\nContent-Length: 187\n\n{\n  \"failedUrl\" : \"https://clientdomain.com/failed\",\n  \"successUrls\" : [\n    \"https://clientdomain.com/fast\",\n    \"https://clientdomain.com/medium\",\n    \"https://clientdomain.com/slow\"\n  ] \n}\n\n201 Created\nLocation: https://example.org/subscription/1\n```\n\n\\\nThe following examples show how the various expressions evaluate, assuming the callback operation has a path parameter named `eventType` and a query parameter named `queryUrl`.\n\nExpression | Value\n---|:---\n$url | https://example.org/subscribe/myevent?queryUrl=https://clientdomain.com/stillrunning\n$method | POST\n$request.path.eventType | myevent\n$request.query.queryUrl | https://clientdomain.com/stillrunning\n$request.header.content-Type | application/json\n$request.body#/failedUrl | https://clientdomain.com/failed\n$request.body#/successUrls/2 | https://clientdomain.com/medium\n$response.header.Location | https://example.org/subscription/1\n##### Callback Examples\n\nThe following example uses the user provided `queryUrl` query string parameter to define the callback URL. This is an example of how to use a callback object to describe a WebHook callback that goes with the subscription operation to enable registering for the WebHook.\n\n\\\nYAML\n```myCallback:\n  '{ $request.query.queryUrl }':\n    post:\n      requestBody:\n        description: Callback payload\n        content:\n          'application/json':\n            schema:\n              $ref: '#/components/schemas/SomePayload'\n      responses:\n        '200':\n          description: callback successfully processed\n```\n\n\\\nThe following example shows a callback where the server is hard-coded, but the query string parameters are populated from the `id` and `email` property in the request body.\n\n\\\nYAML\n```transactionCallback:\n  'http://notificationServer.com?transactionId={$request.body#/id}&email={$request.body#/email}':\n    post:\n      requestBody:\n        description: Callback payload\n        content:\n          'application/json':\n            schema:\n              $ref: '#/components/schemas/SomePayload'\n      responses:\n        '200':\n          description: callback successfully processed\n```\n",
-    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
+    targetSpecs: OpenAPI31,
   },
 ];
 

diff --git a/packages/apidom-ls/src/config/openapi/callback/lint/values--type.ts b/packages/apidom-ls/src/config/openapi/callback/lint/values--type.ts
@@ -2,6 +2,7 @@ import { DiagnosticSeverity } from 'vscode-languageserver-types';
 
 import ApilintCodes from '../../../codes';
 import { LinterMeta } from '../../../../apidom-language-types';
+import { OpenAPI3 } from '../../target-specs';
 
 const valuesTypeLint: LinterMeta = {
   code: ApilintCodes.OPENAPI3_0_CALLBACK_VALUES_TYPE,
@@ -12,6 +13,7 @@ const valuesTypeLint: LinterMeta = {
   linterParams: [['pathItem']],
   marker: 'key',
   data: {},
+  targetSpecs: OpenAPI3,
 };
 
 export default valuesTypeLint;