fix(apidom-ls): make formatting of JSON/YAML better (#1305)

Refs #1284

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

@@ -4,12 +4,15 @@
  */
 
 const transform = (str) => {
-  console.log(JSON.stringify(str.trim().replace(/(\r\n|\n|\r)/gm, '\n')));
+  const transformed = JSON.stringify(str.trim().replace(/(\r\n|\n|\r)/gm, '\n'));
+  const jsonTransformed = transformed.replace(/```json/m, '\n\\\nJSON\n```json');
+  const yamlTransformed = jsonTransformed.replace(/```yaml/m, '\n\\\nYAML\n```yaml');
+  console.log(yamlTransformed);
 };
 
 transform(
-  `[Contact Object](https://www.asyncapi.com/docs/specifications/v2.3.0#contactObject)
-\\
-\\
-Contact information for the exposed API.`,
+  `\`\`\`json
+  test
+  \`\`\`
+  `,
 );

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

@@ -119,7 +119,7 @@ const asyncapiRootComplete: ApidomCompletionItem[] = [
     documentation: {
       kind: 'markdown',
       value:
-        '#### 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```',
+        '#### 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\n\\\nJSON\n```json\n{\n  "description": "Find more info here",\n  "url": "https://example.com"\n}\n```\n\n\n\\\nYAML\n```yaml\ndescription: Find more info here\nurl: https://example.com\n```',
     },
   },
   {

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

@@ -9,7 +9,7 @@ const asyncapi2Docs = [
   },
   {
     target: 'info',
-    docs: 'The object provides metadata about the API. The metadata can be used by the clients if needed.',
+    docs: '[Info Object](https://www.asyncapi.com/docs/specifications/v2.3.0#infoObject)\n\\\n\\\nThe object provides metadata about the API. The metadata can be used by the clients if needed.',
   },
   {
     target: 'servers',

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

@@ -12,7 +12,7 @@ const contactDocs = [
     docs: 'The email address of the contact person/organization. **MUST** be in the format of an email address.',
   },
   {
-    docs: '#### Contact Object\n\nContact information for the exposed API.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nname | `string` | The identifying name of the contact person/organization.\nurl | `string` | The URL pointing to the contact information. MUST be in the format of a URL.\nemail | `string` | The email address of the contact person/organization. MUST be in the format of an email address.\n\n\\\nThis object can be extended with [Specification Extensions](https://www.asyncapi.com/docs/specifications/v2.3.0#specificationExtensions).\n\n##### Contact Object Example:\n\n```json\n{\n  "name": "API Support",\n  "url": "https://www.example.com/support",\n  "email": "[email protected]"\n}\n```\n\n```yaml\nname: API Support\nurl: https://www.example.com/support\nemail: [email protected]\n```',
+    docs: '#### Contact Object\n\nContact information for the exposed API.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nname | `string` | The identifying name of the contact person/organization.\nurl | `string` | The URL pointing to the contact information. MUST be in the format of a URL.\nemail | `string` | The email address of the contact person/organization. MUST be in the format of an email address.\n\n\\\nThis object can be extended with [Specification Extensions](https://www.asyncapi.com/docs/specifications/v2.3.0#specificationExtensions).\n\n##### Contact Object Example:\n\n\n\\\nJSON\n```json\n{\n  "name": "API Support",\n  "url": "https://www.example.com/support",\n  "email": "[email protected]"\n}\n```\n\n\n\\\nYAML\n```yaml\nname: API Support\nurl: https://www.example.com/support\nemail: [email protected]\n```',
   },
 ];
 export default contactDocs;

packages/apidom-ls/src/config/asyncapi/external-documentation/docs/externaldocs.ts

@@ -1,6 +1,6 @@
 const externalDocsDocs = [
   {
-    docs: '#### 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```',
+    docs: '#### 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\n\\\nJSON\n```json\n{\n  "description": "Find more info here",\n  "url": "https://example.com"\n}\n```\n\n\n\\\nYAML\n```yaml\ndescription: Find more info here\nurl: https://example.com\n```',
   },
   {
     target: 'url',

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

@@ -8,7 +8,7 @@ const licenseDocs = [
     docs: 'A URL to the license used for the API. **MUST** be in the format of a URL.',
   },
   {
-    docs: '#### License Object\n\nLicense information for the exposed API.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nname | `string` | **Required.** The license name used for the API.\nurl | `string` | A URL to the license used for the API. MUST be in the format of a URL.\n\n\\\nThis object can be extended with [Specification Extensions](https://www.asyncapi.com/docs/specifications/v2.3.0#specificationExtensions).\n\n##### License Object Example:\n\n```json\n{\n  "name": "Apache 2.0",\n  "url": "https://www.apache.org/licenses/LICENSE-2.0.html"\n}\n```\n\n```yaml\nname: Apache 2.0\nurl: https://www.apache.org/licenses/LICENSE-2.0.html\n```',
+    docs: '#### License Object\n\nLicense information for the exposed API.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nname | `string` | **Required.** The license name used for the API.\nurl | `string` | A URL to the license used for the API. MUST be in the format of a URL.\n\n\\\nThis object can be extended with [Specification Extensions](https://www.asyncapi.com/docs/specifications/v2.3.0#specificationExtensions).\n\n##### License Object Example:\n\n\n\\\nJSON\n```json\n{\n  "name": "Apache 2.0",\n  "url": "https://www.apache.org/licenses/LICENSE-2.0.html"\n}\n```\n\n\n\\\nYAML\n```yaml\nname: Apache 2.0\nurl: https://www.apache.org/licenses/LICENSE-2.0.html\n```',
   },
 ];
 export default licenseDocs;

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

@@ -32,7 +32,7 @@ const operationDocs = [
     docs: '[Message Object](https://www.asyncapi.com/docs/specifications/v2.3.0#messageObject) | [Reference Object](https://www.asyncapi.com/docs/specifications/v2.3.0#referenceObject) | Map["oneOf", [[Message Object](https://www.asyncapi.com/docs/specifications/v2.3.0#messageObject) | [Reference Object](https://www.asyncapi.com/docs/specifications/v2.3.0#referenceObject)]]\n\\\n\\\nA definition of the message that will be published or received by this operation. Map containing a single `oneOf` key is allowed here to specify multiple messages. However, **a message MUST be valid only against one of the message objects.**',
   },
   {
-    docs: '#### Operation Object\n\nDescribes a publish or a subscribe operation. This provides a place to document how and why messages are sent and received.\n\\\n\\\nFor example, an operation might describe a chat application use case where a user sends a text message to a group. A publish operation describes messages that are received by the chat application, whereas a subscribe operation describes messages that are sent by the chat application.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\noperationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.\nsummary | `string` | A short summary of what the operation is about.\ndescription | `string` | A verbose explanation of the operation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation.\ntags | [Tags Object](https://www.asyncapi.com/docs/specifications/v2.3.0#tagsObject) | A list of tags for API documentation control. Tags can be used for logical grouping of operations.\nexternalDocs | [External Documentation Object](https://www.asyncapi.com/docs/specifications/v2.3.0#externalDocumentationObject) | Additional external documentation for this operation.\nbindings | [Operation Bindings Object](https://www.asyncapi.com/docs/specifications/v2.3.0#operationBindingsObject) \\| [Reference Object](https://www.asyncapi.com/docs/specifications/v2.3.0#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation.\ntraits | [[Operation Trait Object](https://www.asyncapi.com/docs/specifications/v2.3.0#operationTraitObject) | [Reference Object](https://www.asyncapi.com/docs/specifications/v2.3.0#referenceObject) ] | A list of traits to apply to the operation object. Traits MUST be merged into the operation object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined here.\nmessage | [Message Object](https://www.asyncapi.com/docs/specifications/v2.3.0#messageObject) | [Reference Object](https://www.asyncapi.com/docs/specifications/v2.3.0#referenceObject) | Map["oneOf", [[Message Object](https://www.asyncapi.com/docs/specifications/v2.3.0#messageObject) | [Reference Object](https://www.asyncapi.com/docs/specifications/v2.3.0#referenceObject)]] | A definition of the message that will be published or received by this operation. Map containing a single `oneOf` key is allowed here to specify multiple messages. However, **a message MUST be valid only against one of the message objects.**\n\n\\\nThis object can be extended with [Specification Extensions](https://www.asyncapi.com/docs/specifications/v2.3.0#specificationExtensions).\n\n##### Operation Object Example\n\n```json\n{\n  "operationId": "registerUser",\n  "summary": "Action to sign a user up.",\n  "description": "A longer description",\n  "tags": [\n    { "name": "user" },\n    { "name": "signup" },\n    { "name": "register" }\n  ],\n  "message": {\n    "headers": {\n      "type": "object",\n      "properties": {\n        "applicationInstanceId": {\n          "description": "Unique identifier for a given instance of the publishing application",\n          "type": "string"\n        }\n      }\n    },\n    "payload": {\n      "type": "object",\n      "properties": {\n        "user": {\n          "$ref": "#/components/schemas/userCreate"\n        },\n        "signup": {\n          "$ref": "#/components/schemas/signup"\n        }\n      }\n    }\n  },\n  "bindings": {\n    "amqp": {\n      "ack": false\n    }\n  },\n  "traits": [\n    { "$ref": "#/components/operationTraits/kafka" }\n  ]\n}\n```\n\n```yaml\noperationId: registerUser\nsummary: Action to sign a user up.\ndescription: A longer description\ntags:\n  - name: user\n  - name: signup\n  - name: register\nmessage:\n  headers:\n    type: object\n    properties:\n      applicationInstanceId:\n        description: Unique identifier for a given instance of the publishing application\n        type: string\n  payload:\n    type: object\n    properties:\n      user:\n        $ref: "#/components/schemas/userCreate"\n      signup:\n        $ref: "#/components/schemas/signup"\nbindings:\n  amqp:\n    ack: false\ntraits:\n  - $ref: "#/components/operationTraits/kafka"\n```',
+    docs: '#### Operation Object\n\nDescribes a publish or a subscribe operation. This provides a place to document how and why messages are sent and received.\n\\\n\\\nFor example, an operation might describe a chat application use case where a user sends a text message to a group. A publish operation describes messages that are received by the chat application, whereas a subscribe operation describes messages that are sent by the chat application.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\noperationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.\nsummary | `string` | A short summary of what the operation is about.\ndescription | `string` | A verbose explanation of the operation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation.\ntags | [Tags Object](https://www.asyncapi.com/docs/specifications/v2.3.0#tagsObject) | A list of tags for API documentation control. Tags can be used for logical grouping of operations.\nexternalDocs | [External Documentation Object](https://www.asyncapi.com/docs/specifications/v2.3.0#externalDocumentationObject) | Additional external documentation for this operation.\nbindings | [Operation Bindings Object](https://www.asyncapi.com/docs/specifications/v2.3.0#operationBindingsObject) \\| [Reference Object](https://www.asyncapi.com/docs/specifications/v2.3.0#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation.\ntraits | [[Operation Trait Object](https://www.asyncapi.com/docs/specifications/v2.3.0#operationTraitObject) | [Reference Object](https://www.asyncapi.com/docs/specifications/v2.3.0#referenceObject) ] | A list of traits to apply to the operation object. Traits MUST be merged into the operation object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined here.\nmessage | [Message Object](https://www.asyncapi.com/docs/specifications/v2.3.0#messageObject) | [Reference Object](https://www.asyncapi.com/docs/specifications/v2.3.0#referenceObject) | Map["oneOf", [[Message Object](https://www.asyncapi.com/docs/specifications/v2.3.0#messageObject) | [Reference Object](https://www.asyncapi.com/docs/specifications/v2.3.0#referenceObject)]] | A definition of the message that will be published or received by this operation. Map containing a single `oneOf` key is allowed here to specify multiple messages. However, **a message MUST be valid only against one of the message objects.**\n\n\\\nThis object can be extended with [Specification Extensions](https://www.asyncapi.com/docs/specifications/v2.3.0#specificationExtensions).\n\n##### Operation Object Example\n\n\n\\\nJSON\n```json\n{\n  "operationId": "registerUser",\n  "summary": "Action to sign a user up.",\n  "description": "A longer description",\n  "tags": [\n    { "name": "user" },\n    { "name": "signup" },\n    { "name": "register" }\n  ],\n  "message": {\n    "headers": {\n      "type": "object",\n      "properties": {\n        "applicationInstanceId": {\n          "description": "Unique identifier for a given instance of the publishing application",\n          "type": "string"\n        }\n      }\n    },\n    "payload": {\n      "type": "object",\n      "properties": {\n        "user": {\n          "$ref": "#/components/schemas/userCreate"\n        },\n        "signup": {\n          "$ref": "#/components/schemas/signup"\n        }\n      }\n    }\n  },\n  "bindings": {\n    "amqp": {\n      "ack": false\n    }\n  },\n  "traits": [\n    { "$ref": "#/components/operationTraits/kafka" }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\noperationId: registerUser\nsummary: Action to sign a user up.\ndescription: A longer description\ntags:\n  - name: user\n  - name: signup\n  - name: register\nmessage:\n  headers:\n    type: object\n    properties:\n      applicationInstanceId:\n        description: Unique identifier for a given instance of the publishing application\n        type: string\n  payload:\n    type: object\n    properties:\n      user:\n        $ref: "#/components/schemas/userCreate"\n      signup:\n        $ref: "#/components/schemas/signup"\nbindings:\n  amqp:\n    ack: false\ntraits:\n  - $ref: "#/components/operationTraits/kafka"\n```',
   },
 ];
 export default operationDocs;