fix(apidom-ls): fix all documentation URLs to point to AsyncAPI 2.3.0 docs (#1286)

Closes #1284

Author: char0n

packages/apidom-ls/scripts/transform-spec-fragment.js

@@ -0,0 +1,41 @@
+/**
+ * Before using transform function please use
+ * this tool https://markdown-it.github.io/ to verify how your Markdown renders.
+ */
+
+const transform = (str) => {
+  console.log(JSON.stringify(str.trim().replace(/(\r\n|\n|\r)/gm, '\n')));
+};
+
+transform(
+  `#### Servers Object
+
+The Servers Object is a map of [Server Objects](https://www.asyncapi.com/docs/specifications/v2.3.0#serverObject).
+
+##### Patterned Fields
+
+Field Pattern | Type | Description
+---|:---:|---
+\`^[A-Za-z0-9_\\-]+$\` | [Server Object](https://www.asyncapi.com/docs/specifications/v2.3.0#serverObject) | The definition of a server this application MAY connect to.
+
+##### Servers Object Example
+
+\`\`\`json
+{
+  "production": {
+    "url": "development.gigantic-server.com",
+    "description": "Development server",
+    "protocol": "kafka",
+    "protocolVersion": "1.0.0"
+  }
+}
+\`\`\`
+
+\`\`\`yaml
+production:
+  url: development.gigantic-server.com
+  description: Development server
+  protocol: kafka
+  protocolVersion: '1.0.0'
+\`\`\``,
+);

packages/apidom-ls/src/config/asyncapi/asyncapi2/complete/asyncapi2.ts

@@ -28,7 +28,7 @@ const asyncapiRootComplete: ApidomCompletionItem[] = [
     documentation: {
       kind: 'markdown',
       value:
-        'The version string signifies the version of the AsyncAPI Specification that the document complies to. The format for this string _must_ be `major`.`minor`.`patch`. The `patch` _may_ be suffixed by a hyphen and extra alphanumeric characters.\n\n ---- \n\nA `major`.`minor` shall be used to designate the AsyncAPI Specification version, and will be considered compatible with the AsyncAPI Specification specified by that `major`.`minor` version. The patch version will not be considered by tooling, making no distinction between `1.0.0` and `1.0.1`.\n\n ---- \n\nIn subsequent versions of the AsyncAPI Specification, care will be given such that increments of the `minor` version should not interfere with operations of tooling developed to a lower minor version. Thus a hypothetical `1.1.0` specification should be usable with tooling designed for `1.0.0`.\n\n',
+        'The version string signifies the version of the AsyncAPI Specification that the document complies to.\nThe format for this string _must_ be `major`.`minor`.`patch`.  The `patch` _may_ be suffixed by a hyphen and extra alphanumeric characters.\n\\\n\\\nA `major`.`minor` shall be used to designate the AsyncAPI Specification version, and will be considered compatible with the AsyncAPI Specification specified by that `major`.`minor` version. The patch version will not be considered by tooling, making no distinction between `1.0.0` and `1.0.1`.\n\\\n\\\nIn subsequent versions of the AsyncAPI Specification, care will be given such that increments of the `minor` version should not interfere with operations of tooling developed to a lower minor version. Thus a hypothetical `1.1.0` specification should be usable with tooling designed for `1.0.0`.',
     },
   },
   {
@@ -41,7 +41,7 @@ const asyncapiRootComplete: ApidomCompletionItem[] = [
     documentation: {
       kind: 'markdown',
       value:
-        'This field represents a unique universal identifier of the [application](https://www.asyncapi.com/docs/specifications/v2.2.0#definitionsApplication) the AsyncAPI document is defining. It must conform to the URI format, according to [RFC3986](https://tools.ietf.org/html/rfc3986).\n\n ---- \n\nIt is **RECOMMENDED** to use a [URN](https://tools.ietf.org/html/rfc8141) to globally and uniquely identify the application during long periods of time, even after it becomes unavailable or ceases to exist.',
+        'This field represents a unique universal identifier of the [application](https://www.asyncapi.com/docs/specifications/v2.3.0#definitionsApplication) the AsyncAPI document is defining. It must conform to the URI format, according to [RFC3986](https://tools.ietf.org/html/rfc3986).\n\\\n\\\nIt is RECOMMENDED to use a [URN](https://tools.ietf.org/html/rfc8141) to globally and uniquely identify the application during long periods of time, even after it becomes unavailable or ceases to exist.',
     },
   },
   {
@@ -54,7 +54,7 @@ const asyncapiRootComplete: ApidomCompletionItem[] = [
     documentation: {
       kind: 'markdown',
       value:
-        "A string representing the default content type to use when encoding/decoding a message's payload. The value **MUST** be a specific media type (e.g. `application/json`). This value **MUST** be used by schema parsers when the [contentType](https://www.asyncapi.com/docs/specifications/v2.2.0#messageObjectContentType) property is omitted.",
+        "A string representing the default content type to use when encoding/decoding a message's payload. The value MUST be a specific media type (e.g. `application/json`). This value MUST be used by schema parsers when the [contentType](https://www.asyncapi.com/docs/specifications/v2.3.0#messageObjectContentType) property is omitted.\n\\\n\\\nIn case a message can't be encoded/decoded using this value, schema parsers MUST use their default content type.",
     },
   },
   {
@@ -67,7 +67,7 @@ const asyncapiRootComplete: ApidomCompletionItem[] = [
     documentation: {
       kind: 'markdown',
       value:
-        'Holds the relative paths to the individual channel and their operations. Channel paths are relative to servers.\n\n ---- \n\nChannels are also known as "topics", "routing keys", "event types" or "paths".',
+        'Holds the relative paths to the individual channel and their operations. Channel paths are relative to servers.\n\\\n\\\nChannels are also known as "topics", "routing keys", "event types" or "paths".',
     },
   },
   {
@@ -80,7 +80,7 @@ const asyncapiRootComplete: ApidomCompletionItem[] = [
     documentation: {
       kind: 'markdown',
       value:
-        'The Servers Object is a map of [Server Objects](https://www.asyncapi.com/docs/specifications/v2.2.0#serverObject).',
+        'The Servers Object is a map of [Server Objects](https://www.asyncapi.com/docs/specifications/v2.3.0#serverObject).',
     },
   },
   {
@@ -119,7 +119,7 @@ const asyncapiRootComplete: ApidomCompletionItem[] = [
     documentation: {
       kind: 'markdown',
       value:
-        '#### External Documentation Object\n\n ---- \n\nnAllows referencing an external resource for extended documentation.\n\n ---- \n\n##### Fixed Fields\n\n ---- \n\n**description** (`string`) : A short description of the target documentation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation.\n\n ---- \n\n**url** (`string`) : **Required.** The URL for the target documentation. Value MUST be in the format of a URL.\n\n ---- \n\nThis object can be extended with [Specification Extensions](https://www.asyncapi.com/docs/specifications/v2.2.0#specificationExtensions).',
+        '#### External Documentation Object\n\\\nAllows referencing an external resource for extended documentation.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\ndescription | `string` | A short description of the target documentation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation.\nurl | `string` | **Required.** The URL for the target documentation. Value MUST be in the format of a URL.\n\nThis object can be extended with [Specification Extensions](https://www.asyncapi.com/docs/specifications/v2.3.0#specificationExtensions).\n\n##### External Documentation Object Example\n\n```json\n{\n  "description": "Find more info here",\n  "url": "https://example.com"\n}\n```\n\n```yaml\ndescription: Find more info here\nurl: https://example.com\n```',
     },
   },
   {

packages/apidom-ls/src/config/asyncapi/asyncapi2/docs/asyncapi2.ts

@@ -1,27 +1,27 @@
 const asyncapi2Docs = [
   {
     target: 'asyncapi',
-    docs: 'The version string signifies the version of the AsyncAPI Specification that the document complies to. The format for this string _must_ be `major`.`minor`.`patch`. The `patch` _may_ be suffixed by a hyphen and extra alphanumeric characters.\n\n ---- \n\nA `major`.`minor` shall be used to designate the AsyncAPI Specification version, and will be considered compatible with the AsyncAPI Specification specified by that `major`.`minor` version. The patch version will not be considered by tooling, making no distinction between `1.0.0` and `1.0.1`.\n\n ---- \n\nIn subsequent versions of the AsyncAPI Specification, care will be given such that increments of the `minor` version should not interfere with operations of tooling developed to a lower minor version. Thus a hypothetical `1.1.0` specification should be usable with tooling designed for `1.0.0`.\n\n',
+    docs: 'The version string signifies the version of the AsyncAPI Specification that the document complies to.\nThe format for this string _must_ be `major`.`minor`.`patch`.  The `patch` _may_ be suffixed by a hyphen and extra alphanumeric characters.\n\\\n\\\nA `major`.`minor` shall be used to designate the AsyncAPI Specification version, and will be considered compatible with the AsyncAPI Specification specified by that `major`.`minor` version. The patch version will not be considered by tooling, making no distinction between `1.0.0` and `1.0.1`.\n\\\n\\\nIn subsequent versions of the AsyncAPI Specification, care will be given such that increments of the `minor` version should not interfere with operations of tooling developed to a lower minor version. Thus a hypothetical `1.1.0` specification should be usable with tooling designed for `1.0.0`.',
   },
   {
     target: 'id',
-    docs: 'This field represents a unique universal identifier of the [application](https://www.asyncapi.com/docs/specifications/v2.2.0#definitionsApplication) the AsyncAPI document is defining. It must conform to the URI format, according to [RFC3986](https://tools.ietf.org/html/rfc3986).\n\n ---- \n\nIt is **RECOMMENDED** to use a [URN](https://tools.ietf.org/html/rfc8141) to globally and uniquely identify the application during long periods of time, even after it becomes unavailable or ceases to exist.',
+    docs: 'This field represents a unique universal identifier of the [application](https://www.asyncapi.com/docs/specifications/v2.3.0#definitionsApplication) the AsyncAPI document is defining. It must conform to the URI format, according to [RFC3986](https://tools.ietf.org/html/rfc3986).\n\\\n\\\nIt is RECOMMENDED to use a [URN](https://tools.ietf.org/html/rfc8141) to globally and uniquely identify the application during long periods of time, even after it becomes unavailable or ceases to exist.',
   },
   {
     target: 'info',
     docs: 'The object provides metadata about the API. The metadata can be used by the clients if needed.',
   },
   {
     target: 'servers',
-    docs: 'The Servers Object is a map of [Server Objects](https://www.asyncapi.com/docs/specifications/v2.2.0#serverObject).',
+    docs: 'The Servers Object is a map of [Server Objects](https://www.asyncapi.com/docs/specifications/v2.3.0#serverObject).',
   },
   {
     target: 'defaultContentType',
-    docs: "A string representing the default content type to use when encoding/decoding a message's payload. The value **MUST** be a specific media type (e.g. `application/json`). This value **MUST** be used by schema parsers when the [contentType](https://www.asyncapi.com/docs/specifications/v2.2.0#messageObjectContentType) property is omitted.",
+    docs: "A string representing the default content type to use when encoding/decoding a message's payload. The value MUST be a specific media type (e.g. `application/json`). This value MUST be used by schema parsers when the [contentType](https://www.asyncapi.com/docs/specifications/v2.3.0#messageObjectContentType) property is omitted.\n\\\n\\\nIn case a message can't be encoded/decoded using this value, schema parsers MUST use their default content type.",
   },
   {
     target: 'channels',
-    docs: 'Holds the relative paths to the individual channel and their operations. Channel paths are relative to servers.\n\n ---- \n\nChannels are also known as "topics", "routing keys", "event types" or "paths".',
+    docs: 'Holds the relative paths to the individual channel and their operations. Channel paths are relative to servers.\n\\\n\\\nChannels are also known as "topics", "routing keys", "event types" or "paths".',
   },
   {
     target: 'components',
@@ -31,5 +31,9 @@ const asyncapi2Docs = [
     target: 'tags',
     docs: 'A list of tags used by the specification with additional metadata. Each tag name in the list **MUST** be unique.',
   },
+  {
+    target: 'externalDocs',
+    docs: 'Additional external documentation.',
+  },
 ];
 export default asyncapi2Docs;

packages/apidom-ls/src/config/asyncapi/channel-item/complete/channel-item.ts

@@ -15,7 +15,7 @@ const channelCompleteJson: ApidomCompletionItem[] = [
     documentation: {
       kind: 'markdown',
       value:
-        "Allows for an external definition of this channel item.\n\n ---- \n\nThe referenced structure **MUST** be in the format of a [Channel Item Object](https://www.asyncapi.com/docs/specifications/v2.2.0#channelItemObject). \n\n ---- \n\nIf there are conflicts between the referenced definition and this Channel Item's definition, the behavior is _undefined_.",
+        "Allows for an external definition of this channel item. The referenced structure MUST be in the format of a [Channel Item Object](https://www.asyncapi.com/docs/specifications/v2.3.0#channelItemObject). If there are conflicts between the referenced definition and this Channel Item's definition, the behavior is *undefined*.\n\\\n\\\n**Deprecated:** Usage of the `$ref` property has been deprecated.",
     },
   },
   {
@@ -41,7 +41,7 @@ const channelCompleteJson: ApidomCompletionItem[] = [
     documentation: {
       kind: 'markdown',
       value:
-        'The servers on which this channel is available, specified as an optional unordered list of names (string keys) of [Server Objects](https://www.asyncapi.com/docs/specifications/v2.2.0#serverObject) defined in the [Servers Object](https://www.asyncapi.com/docs/specifications/v2.2.0#serversObject) (a map). If `servers` is absent or empty then this channel must be available on all servers defined in the [Servers Object](https://www.asyncapi.com/docs/specifications/v2.2.0#serversObject).',
+        'The servers on which this channel is available, specified as an optional unordered list of names (string keys) of [Server Objects](https://www.asyncapi.com/docs/specifications/v2.3.0#serverObject) defined in the [Servers Object](https://www.asyncapi.com/docs/specifications/v2.3.0#serversObject) (a map). If `servers` is absent or empty then this channel must be available on all servers defined in the [Servers Object](https://www.asyncapi.com/docs/specifications/v2.3.0#serversObject).',
     },
   },
   {
@@ -54,7 +54,7 @@ const channelCompleteJson: ApidomCompletionItem[] = [
     documentation: {
       kind: 'markdown',
       value:
-        '[Operation Object](https://www.asyncapi.com/docs/specifications/v2.2.0#operationObject)\n\n ---- \n\nA definition of the SUBSCRIBE operation, which defines the messages produced by the application and sent to the channel.',
+        '#### [Operation Object](https://www.asyncapi.com/docs/specifications/v2.3.0#operationObject)\nA definition of the SUBSCRIBE operation, which defines the messages produced by the application and sent to the channel.',
     },
   },
   {
@@ -67,7 +67,7 @@ const channelCompleteJson: ApidomCompletionItem[] = [
     documentation: {
       kind: 'markdown',
       value:
-        '[Operation Object](https://www.asyncapi.com/docs/specifications/v2.2.0#operationObject)\n\n ---- \n\nA definition of the PUBLISH operation, which defines the messages consumed by the application from the channel.',
+        '#### [Operation Object](https://www.asyncapi.com/docs/specifications/v2.3.0#operationObject)\nA definition of the PUBLISH operation, which defines the messages consumed by the application from the channel.',
     },
   },
   {
@@ -80,7 +80,7 @@ const channelCompleteJson: ApidomCompletionItem[] = [
     documentation: {
       kind: 'markdown',
       value:
-        '[Parameters Object](https://www.asyncapi.com/docs/specifications/v2.2.0#parametersObject)\n\n ---- \n\nA map of the parameters included in the channel name. It **SHOULD** be present only when using channels with expressions (as defined by [RFC 6570 section 2.2](https://tools.ietf.org/html/rfc6570#section-2.2)).',
+        '#### [Parameters Object](https://www.asyncapi.com/docs/specifications/v2.3.0#parametersObject)\nA map of the parameters included in the channel name. It SHOULD be present only when using channels with expressions (as defined by [RFC 6570 section 2.2](https://tools.ietf.org/html/rfc6570#section-2.2)).',
     },
   },
   {
@@ -93,7 +93,7 @@ const channelCompleteJson: ApidomCompletionItem[] = [
     documentation: {
       kind: 'markdown',
       value:
-        '[Channel Bindings Object](https://www.asyncapi.com/docs/specifications/v2.2.0#channelBindingsObject) | [Reference Object](https://www.asyncapi.com/docs/specifications/v2.2.0#referenceObject)\n\n ---- \n\nA map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the channel.\n\n ---- \n\nThis object can be extended with [Specification Extensions](https://www.asyncapi.com/docs/specifications/v2.2.0#specificationExtensions).',
+        '#### [Channel Bindings Object](https://www.asyncapi.com/docs/specifications/v2.3.0#channelBindingsObject) \\| [Reference Object](https://www.asyncapi.com/docs/specifications/v2.3.0#referenceObject)\nA map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the channel.',
     },
   },
   {