diff --git a/packages/apidom-ls/src/config/openapi/config.ts b/packages/apidom-ls/src/config/openapi/config.ts index cba6fec9ee..69ae485abf 100644 --- a/packages/apidom-ls/src/config/openapi/config.ts +++ b/packages/apidom-ls/src/config/openapi/config.ts @@ -1,5 +1,16 @@ import infoMeta from './info/meta'; import contactMeta from './contact/meta'; +import licenseMeta from './license/meta'; +import tagMeta from './tag/meta'; +import externalDocumentationMeta from './external-documentation/meta'; +import operationMeta from './operation/meta'; +import parameterMeta from './parameter/meta'; +import pathItemMeta from './path-item/meta'; +import pathsMeta from './paths/meta'; +import responsesMeta from './responses/meta'; +import serverMeta from './server/meta'; +import serverVariableMeta from './server-variable/meta'; +import openapi3_1Meta from './openapi3_1/meta'; import schemaMeta from '../common/schema/meta'; import ApilintCodes from '../codes'; @@ -18,5 +29,17 @@ export default { }, info: infoMeta, contact: contactMeta, + license: licenseMeta, schema: schemaMeta, + operation: operationMeta, + parameter: parameterMeta, + parameters: parameterMeta, + pathItem: pathItemMeta, + paths: pathsMeta, + responses: responsesMeta, + server: serverMeta, + serverVariable: serverVariableMeta, + tag: tagMeta, + externalDocumentation: externalDocumentationMeta, + openApi3_1: openapi3_1Meta, }; diff --git a/packages/apidom-ls/src/config/openapi/external-documentation/documentation.ts b/packages/apidom-ls/src/config/openapi/external-documentation/documentation.ts new file mode 100644 index 0000000000..3593093ea4 --- /dev/null +++ b/packages/apidom-ls/src/config/openapi/external-documentation/documentation.ts @@ -0,0 +1,16 @@ +const documentation = [ + { + target: 'url', + docs: '**REQUIRED**. The URL for the target documentation. This MUST be in the form of a URL.', + }, + { + target: 'description', + docs: 'A description of the target documentation. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.', + }, + { + docs: '#### [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#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 description of the target documentation. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nurl | `string` | **REQUIRED**. The URL for the target documentation. This MUST be in the form of a URL.\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##### 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```', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, +]; + +export default documentation; diff --git a/packages/apidom-ls/src/config/openapi/external-documentation/meta.ts b/packages/apidom-ls/src/config/openapi/external-documentation/meta.ts new file mode 100644 index 0000000000..33a6f79694 --- /dev/null +++ b/packages/apidom-ls/src/config/openapi/external-documentation/meta.ts @@ -0,0 +1,8 @@ +import documentation from './documentation'; +import { FormatMeta } from '../../../apidom-language-types'; + +const meta: FormatMeta = { + documentation, +}; + +export default meta; diff --git a/packages/apidom-ls/src/config/openapi/license/documentation.ts b/packages/apidom-ls/src/config/openapi/license/documentation.ts new file mode 100644 index 0000000000..6e743eaa19 --- /dev/null +++ b/packages/apidom-ls/src/config/openapi/license/documentation.ts @@ -0,0 +1,22 @@ +const documentation = [ + { + target: 'name', + docs: '**REQUIRED**. The license name used for the API.', + }, + { + target: 'identifier', + docs: 'An [SPDX](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60) license expression for the API. The `identifier` field is mutually exclusive of the `url` field.', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + { + target: 'url', + docs: 'A URL to the license used for the API. This MUST be in the form of a URL. The `url` field is mutually exclusive of the `identifier` field.', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + { + docs: '#### [License Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#licenseObject)\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.\nidentifier | `string` | An [SPDX](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60) license expression for the API. The `identifier` field is mutually exclusive of the `url` field.\nurl | `string` | A URL to the license used for the API. This MUST be in the form of a URL. The `url` field is mutually exclusive of the `identifier` field.\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##### License Object Example\n\n\n\\\nJSON\n```json\n{\n "name": "Apache 2.0",\n "identifier": "Apache-2.0"\n}\n```\n\n\n\\\nYAML\n```yaml\nname: Apache 2.0\nidentifier: Apache-2.0\n```', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, +]; + +export default documentation; diff --git a/packages/apidom-ls/src/config/openapi/license/meta.ts b/packages/apidom-ls/src/config/openapi/license/meta.ts new file mode 100644 index 0000000000..33a6f79694 --- /dev/null +++ b/packages/apidom-ls/src/config/openapi/license/meta.ts @@ -0,0 +1,8 @@ +import documentation from './documentation'; +import { FormatMeta } from '../../../apidom-language-types'; + +const meta: FormatMeta = { + documentation, +}; + +export default meta; diff --git a/packages/apidom-ls/src/config/openapi/openapi3_1/documentation.ts b/packages/apidom-ls/src/config/openapi/openapi3_1/documentation.ts new file mode 100644 index 0000000000..def6bbdfeb --- /dev/null +++ b/packages/apidom-ls/src/config/openapi/openapi3_1/documentation.ts @@ -0,0 +1,58 @@ +const documentation = [ + { + target: 'openapi', + docs: '`string`\n\n**REQUIRED**. This string MUST be the [version number](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#versions) of the OpenAPI Specification that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling to interpret the OpenAPI document. This is *not* related to the API [`info.version`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#infoVersion) string.', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + { + target: 'jsonSchemaDialect', + docs: '`string`\n\nThe default value for the `$schema` keyword within [Schema Objects](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject) contained within this OAS document. This MUST be in the form of a URI.', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + { + target: 'webhooks', + docs: 'Map[`string`, [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]\n\n The incoming webhooks that MAY be received as part of this API and that the API consumer MAY choose to implement. Closely related to the `callbacks` feature, this section describes requests initiated other than by an API call, for example by an out of band registration. The key name is a unique string to refer to each webhook, while the (optionally referenced) Path Item Object describes a request that may be initiated by the API provider and the expected responses. An [example](https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.1/webhook-example.yaml) is available.', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + { + target: 'security', + docs: '#### [[Security Requirement Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securityRequirementObject)]\n\nA declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition. To make security optional, an empty security requirement ({}) can be included in the array.', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + { + target: 'servers', + docs: '#### [[Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)]\n\nAn array of Server Objects, which provide connectivity information to a target server. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject) with a [url](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverUrl) value of `/`.', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + { + target: 'tags', + docs: "#### [[Tag Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#tagObject)]\n\nA list of tags used by the document with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique.", + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + /** + * The following Fixed Fields are provided as reference, but are more + * comprehensively described by their respective meta documentation + */ + // { + // target: 'info', + // docs: '#### [Info Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#infoObject)\n\n**REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required.', + // targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + // }, + // { + // target: 'paths', + // docs: '#### [Paths Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsObject)\n\nThe available paths and operations for the API.', + // targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + // }, + // { + // target: 'components', + // docs: '#### [Components Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsObject)\n\nAn element to hold various schemas for the document.', + // targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + // }, + // { + // target: 'externalDocs', + // docs: '#### [External Dcoumentation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#externalDocumentationObject)\n\nAdditional external documentation.', + // targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + // }, +]; + +export default documentation; diff --git a/packages/apidom-ls/src/config/openapi/openapi3_1/meta.ts b/packages/apidom-ls/src/config/openapi/openapi3_1/meta.ts new file mode 100644 index 0000000000..33a6f79694 --- /dev/null +++ b/packages/apidom-ls/src/config/openapi/openapi3_1/meta.ts @@ -0,0 +1,8 @@ +import documentation from './documentation'; +import { FormatMeta } from '../../../apidom-language-types'; + +const meta: FormatMeta = { + documentation, +}; + +export default meta; diff --git a/packages/apidom-ls/src/config/openapi/operation/documentation.ts b/packages/apidom-ls/src/config/openapi/operation/documentation.ts new file mode 100644 index 0000000000..59d03a2bef --- /dev/null +++ b/packages/apidom-ls/src/config/openapi/operation/documentation.ts @@ -0,0 +1,62 @@ +const documentation = [ + { + target: 'tags', + docs: '#### [`string`]\n\nA list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.', + }, + { + target: 'summary', + docs: 'A short summary of what the operation does.', + }, + { + target: 'description', + docs: 'A verbose explanation of the operation behavior. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.', + }, + { + target: 'operationId', + docs: '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.', + }, + { + target: 'deprecated', + docs: 'Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`.', + }, + { + target: 'parameters', + docs: "[[Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]\n\nA list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemParameters), the new definition will override it but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Object's components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).", + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + { + target: 'requestBody', + docs: '[[Request Body Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#requestBodyObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]\n\nThe request body applicable for this operation. The requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1), [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)), `requestBody` is permitted but does not have well-defined semantics and SHOULD be avoided if possible.', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + { + target: 'callbacks', + docs: 'Map[`string`, [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]]\n\nA map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject) that describes a request that may be initiated by the API provider and the expected responses.', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + { + target: 'security', + docs: '#### [[Security Requirement Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)]\n\nA declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. To make security optional, an empty security requirement (`{}`) can be included in the array. This definition overrides any declared top-level [`security`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasSecurity). To remove a top-level security declaration, an empty array can be used.', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + { + target: 'servers', + docs: '#### [[Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)]\n\nAn alternative `server` array to service this operation. If an alternative `server` object is specified at the Path Item Object or Root level, it will be overridden by this value.', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + /** + * The following Fixed Field is provided as reference, but is more + * comprehensively described by parent External Documentation Object meta documentation + */ + // { + // target: 'externalDocs', + // docs: '#### [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#externalDocumentationObject)\n\nAdditional external documentation for this operation.', + // targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + // }, + { + docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nDescribes a single API operation on a path.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\ntags | [`string`] | A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.\nsummary | `string` | A short summary of what the operation does.\ndescription | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\texternalDocs | [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#externalDocumentationObject) | Additional external documentation for this operation.\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.\nparameters | [[Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemParameters), the new definition will override it but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Object\'s components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).\nrequestBody | [[Request Body Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#requestBodyObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | The request body applicable for this operation. The requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1), [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)), `requestBody` is permitted but does not have well-defined semantics and SHOULD be avoided if possible.\nresponses | [Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responsesObject) | The list of possible responses as they are returned from executing this operation.\ncallbacks | Map[`string`, [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]] | A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject) that describes a request that may be initiated by the API provider and the expected responses.\ndeprecated |`boolean` | Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`.\nsecurity | [[Security Requirement Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. To make security optional, an empty security requirement (`{}`) can be included in the array. This definition overrides any declared top-level [`security`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasSecurity). To remove a top-level security declaration, an empty array can be used.\nservers | [[Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)] | An alternative server array to service this operation. If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by this value.\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##### Operation Object Example\n\n\n\\\nJSON\n```json\n{\n "tags": [\n "pet"\n ],\n "summary": "Updates a pet in the store with form data",\n "operationId": "updatePetWithForm",\n "parameters": [\n {\n "name": "petId",\n "in": "path",\n "description": "ID of pet that needs to be updated",\n "required": true,\n "schema": {\n "type": "string"\n }\n }\n ],\n "requestBody": {\n "content": {\n "application/x-www-form-urlencoded": {\n "schema": {\n "type": "object",\n "properties": {\n "name": {\n "description": "Updated name of the pet",\n "type": "string"\n },\n "status": {\n "description": "Updated status of the pet",\n "type": "string"\n }\n },\n "required": ["status"]\n }\n }\n }\n },\n "responses": {\n "200": {\n "description": "Pet updated.",\n "content": {\n "application/json": {},\n "application/xml": {}\n }\n },\n "405": {\n "description": "Method Not Allowed",\n "content": {\n "application/json": {},\n "application/xml": {}\n }\n }\n },\n "security": [\n {\n "petstore_auth": [\n "write:pets",\n "read:pets"\n ]\n }\n ]\n}\n```\n\n\n\\\nYAML\n```yaml\ntags:\n- pet\nsummary: Updates a pet in the store with form data\noperationId: updatePetWithForm\nparameters:\n- name: petId\n in: path\n description: ID of pet that needs to be updated\n required: true\n schema:\n type: string\nrequestBody:\n content:\n \'application/x-www-form-urlencoded\':\n schema:\n type: object\n properties:\n name:\n description: Updated name of the pet\n type: string\n status:\n description: Updated status of the pet\n type: string\n required:\n - status\nresponses:\n \'200\':\n description: Pet updated.\n content:\n \'application/json\': {}\n \'application/xml\': {}\n \'405\':\n description: Method Not Allowed\n content:\n \'application/json\': {}\n \'application/xml\': {}\nsecurity:\n- petstore_auth:\n - write: pets\n - read:pets\n```\n', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, +]; + +export default documentation; diff --git a/packages/apidom-ls/src/config/openapi/operation/meta.ts b/packages/apidom-ls/src/config/openapi/operation/meta.ts new file mode 100644 index 0000000000..33a6f79694 --- /dev/null +++ b/packages/apidom-ls/src/config/openapi/operation/meta.ts @@ -0,0 +1,8 @@ +import documentation from './documentation'; +import { FormatMeta } from '../../../apidom-language-types'; + +const meta: FormatMeta = { + documentation, +}; + +export default meta; diff --git a/packages/apidom-ls/src/config/openapi/parameter/documentation.ts b/packages/apidom-ls/src/config/openapi/parameter/documentation.ts new file mode 100644 index 0000000000..b76fba9ffe --- /dev/null +++ b/packages/apidom-ls/src/config/openapi/parameter/documentation.ts @@ -0,0 +1,61 @@ +const documentation = [ + { + target: 'name', + docs: '**REQUIRED**. The name of the parameter. Parameter names are *case sensitive*.\n\n * If [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"path"`, the `name` field MUST correspond to a template expression occurring within the [path](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsPath) field in the [Paths Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsObject). See [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating) for further information.\n\n * If [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.\n\n * For all other cases, the `name` corresponds to the parameter name used by the [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) property.', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + { + target: 'in', + docs: '**REQUIRED**. The location of the parameter. Possible values are `"query"`, `"header"`, `"path"` or `"cookie"`.', + }, + { + target: 'description', + docs: 'A brief description of the parameter. This could contain examples of use. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.', + }, + { + target: 'required', + docs: 'Determines whether this parameter is mandatory. If the [parameter location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"path"`, this property is **REQUIRED** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`.', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + { + target: 'deprecated', + docs: 'Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is `false`.', + }, + { + target: 'allowEmptyValue', + docs: 'Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows sending a parameter with an empty value. Default value is `false`. If [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle) is used, and if behavior is `n/a` (cannot be serialized), the value of `allowEmptyValue` SHALL be ignored. Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision.', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + { + target: 'style', + docs: 'Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of `in`): for `query` - `form`; for `path` - `simple`; for `header` - `simple`; for `cookie` - `form`.', + }, + { + target: 'explode', + docs: 'When this is true, parameter values of type `array` or `object` generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters this property has no effect. When [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`.', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + { + target: 'allowReserved', + docs: "Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&'()*+,;=` to be included without percent - encoding. This property only applies to parameters with an `in` value of `query`. The default value is `false`.", + }, + { + target: 'example', + docs: "Example of the parameter's potential value. The example SHOULD match the specified schema and encoding properties if present. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` that contains an example, the `example` value SHALL *override* the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.", + }, + { + target: 'examples', + docs: "#### Map[`string`, [Example Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#exampleObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]\n\n Examples of the parameter's potential value. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The `examples` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` that contains an example, the `examples` value SHALL *override* the example provided by the schema", + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + { + target: 'content', + docs: 'Map[`string`, [Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject)]\n\nA map containing the representations for the parameter. The key is the media type and the value describes it. The map MUST only contain one entry.', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + { + docs: '#### [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject)\n\nDescribes a single operation parameter.\n\nA unique parameter is defined by a combination of a [name](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn).\n\n##### Parameter Locations\n\nThere are four possible parameter locations specified by the `in` field:\n\n* path - Used together with [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating), where the parameter value is actually part of the operations URL. This does not include the host or base path of the API. For example, in `/items/{ itemId}`, the path parameter is `itemId`.\n* query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`.\n* header - Custom headers that are expected as part of the request. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive.\n* cookie - Used to pass a specific cookie value to the API.\n\n##### Fixed Fields \n\nField Name | Type | Description\n---|:---:|---\nname | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*.\n  |   | * If [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"path"`, the `name` field MUST correspond to a template expression occurring within the [path](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsPath) field in the [Paths Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsObject). See [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating) for further information.\n  |   | * If [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.\n  |   | * For all other cases, the `name` corresponds to the parameter name used by the [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) property.\nin | `string` | **REQUIRED**. The location of the parameter. Possible values are `"query"`, `"header"`, `"path"` or `"cookie"`.\ndescription | `string` | A brief description of the parameter. This could contain examples of use. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nrequired | `boolean` | Determines whether this parameter is mandatory. If the [parameter location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"path"`, this property is **REQUIRED** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`.\ndeprecated | `boolean` | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is `false`.\nallowEmptyValue | `boolean` | Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows sending a parameter with an empty value. Default value is `false`. If [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle) is used, and if behavior is `n/a` (cannot be serialized), the value of `allowEmptyValue` SHALL be ignored. Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision.\n\n\\\nThe rules for serialization of the parameter are specified in one of two ways. For simpler scenarios, a schema and style can describe the structure and syntax of the parameter.\n\nField Name | Type | Description\n---|:---:|---\nstyle | `string` | Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of `in`): for `query` - `form`; for `path` - `simple`; for `header` - `simple`; for `cookie` - `form`.\nexplode | `boolean` | When this is true, parameter values of type `array` or `object` generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters this property has no effect. When [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`.\nallowReserved | `boolean` | Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&\'()*+,;=` to be included without percent - encoding. This property only applies to parameters with an `in` value of `query`. The default value is `false`.\nschema | [Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject) | The schema defining the type used for the parameter.\nexample | Any | Example of the parameter\'s potential value. The example SHOULD match the specified schema and encoding properties if present. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` that contains an example, the `example` value SHALL *override* the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.\nexamples | Map[`string`, [Example Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#exampleObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | Examples of the parameter\'s potential value. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The `examples` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` that contains an example, the `examples` value SHALL *override* the example provided by the schema.\n\n\\\nFor more complex scenarios, the [`content`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterContent) property can define the media type and schema of the parameter. A parameter MUST contain either a `schema` property, or a `content` property, but not both. When `example` or `examples` are provided in conjunction with the `schema` object, the example MUST follow the prescribed serialization strategy for the parameter.\n\nField Name | Type | Description\n---|:---:|---\ncontent | Map[`string`, [Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject)] | A map containing the representations for the parameter. The key is the media type and the value describes it. The map MUST only contain one entry.\n\n##### Style Values\n\nIn order to support common ways of serializing simple parameters, a set of `style` values are defined.\n\n`style` | [`type`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#dataTypes) | `in` | Comments\n---|:---:|---:|---\nmatrix | `primitive`, `array`, `object` | `path` | Path-style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7)\nlabel | `primitive`, `array`, `object` | `path` | Label style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7)\nform | `primitive`, `array`, `object` | `query`, `cookie` | Form style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8). This option replaces `collectionFormat` with a `csv` (when `explode` is false) or `multi` (when `explode` is true) value from OpenAPI 2.0.\nsimple | `array` | `path`, `header` | Simple style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8). This option replaces `collectionFormat` with a `csv` value from OpenAPI 2.0.\nspaceDelimited | `array`, `object` | `query` | Space separated array or object values. This option replaces `collectionFormat` equal to `ssv` from OpenAPI 2.0.\npipeDelimited | `array`, `object` | `query` | Pipe separated array or object values. This option replaces `collectionFormat` equal to `pipes` from OpenAPI 2.0.\ndeepObject | `object` | `query` | Provides a simple way of rendering nested objects using form parameters.\n\n##### Examples\n\nExternal reference link to [Style Examples](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#style-examples)\n\nExternal reference link to [Parameter Object Examples](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameter-object-examples)\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', + }, +]; + +export default documentation; diff --git a/packages/apidom-ls/src/config/openapi/parameter/meta.ts b/packages/apidom-ls/src/config/openapi/parameter/meta.ts new file mode 100644 index 0000000000..33a6f79694 --- /dev/null +++ b/packages/apidom-ls/src/config/openapi/parameter/meta.ts @@ -0,0 +1,8 @@ +import documentation from './documentation'; +import { FormatMeta } from '../../../apidom-language-types'; + +const meta: FormatMeta = { + documentation, +}; + +export default meta; diff --git a/packages/apidom-ls/src/config/openapi/path-item/documentation.ts b/packages/apidom-ls/src/config/openapi/path-item/documentation.ts new file mode 100644 index 0000000000..2fc85c1d48 --- /dev/null +++ b/packages/apidom-ls/src/config/openapi/path-item/documentation.ts @@ -0,0 +1,75 @@ +const documentation = [ + { + target: '$ref', + docs: 'Allows for an external definition of this path item. The referenced structure MUST be in the format of a [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject). In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined. See the rules for resolving [Relative References](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#relativeReferencesURI).', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + { + target: 'summary', + docs: 'An optional string summary, intended to apply to all operations in this path.', + }, + { + target: 'description', + docs: 'An optional string description, intended to apply to all operations in this path. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.', + }, + { + target: 'servers', + docs: '#### [[ServerObject](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)]\n\nAn alternative `server` array to service all operations in this path.', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + { + target: 'parameters', + docs: "#### [[Parameter](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]\n\nA list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Object's components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).", + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + /** + * The following Fixed Fields are provided as reference, but are more + * comprehensively described by parent Operation Object meta documentation + */ + // { + // target: 'get', + // docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nA definition of a GET operation on this path.', + // targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + // }, + // { + // target: 'put', + // docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nA definition of a PUT operation on this path.', + // targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + // }, + // { + // target: 'post', + // docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nA definition of a POST operation on this path.', + // targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + // }, + // { + // target: 'delete', + // docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nA definition of a DELETE operation on this path.', + // targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + // }, + // { + // target: 'options', + // docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nA definition of a OPTIONS operation on this path.', + // targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + // }, + // { + // target: 'head', + // docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nA definition of a HEAD operation on this path.', + // targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + // }, + // { + // target: 'patch', + // docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nA definition of a PATCH operation on this path.', + // targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + // }, + // { + // target: 'trace', + // docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nA definition of a TRACE operation on this path.', + // targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + // }, + { + docs: '#### [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject)\n\nDescribes the operations available on a single path. A Path Item MAY be empty, due to [ACL constraints](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securityFiltering). The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\n$ref | `string` | Allows for a referenced definition of this path item. The referenced structure MUST be in the form of a [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject). In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined. See the rules for resolving [Relative References](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#relativeReferencesURI).\nsummary | `string` | An optional, string summary, intended to apply to all operations in this path.\ndescription | `string` | A description of the API. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\tget | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a GET operation on this path.\nput | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a PUT operation on this path.\npost | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a POST operation on this path.\ndelete | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a DELETE operation on this path.\noptions | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a OPTIONS operation on this path.\nhead | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a HEAD operation on this path.\npatch | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a PATCH operation on this path.\nget | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a GET operation on this path.\ntrace | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a TRACE operation on this path.\nservers | [[Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)] | An alternative `server` array to service all operations in this path.\nparamenters | [[Parameter](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Object\'s components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).\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##### Paths Object Example\n\n\n\\\nJSON\n```json\n{\n "get": {\n "description": "Returns pets based on ID",\n "summary": "Find pets by ID",\n "operationId": "getPetsById",\n "responses": {\n "200": {\n "description": "pet response",\n "content": {\n "*/*": {\n "schema": {\n "type": "array",\n "items": {\n "$ref": "#/components/schemas/Pet"\n }\n }\n }\n }\n },\n "default": {\n "description": "error payload",\n "content": {\n "text/html": {\n "schema": {\n "$ref": "#/components/schemas/ErrorModel"\n }\n }\n }\n }\n }\n },\n "parameters": [\n {\n "name": "id",\n "in": "path",\n "description": "ID of pet to use",\n "required": true,\n "schema": {\n "type": "array",\n "items": {\n "type": "string"\n }\n },\n "style": "simple"\n }\n ]\n}\n```\n\n\n\\\nYAML\n```yaml\nget:\n description: Returns pets based on ID\n summary: Find pets by ID\n operationId: getPetsById\n responses:\n \'200\':\n description: pet response\n content:\n \'*/*\' :\n schema:\n type: array\n items:\n $ref: \'#/components/schemas/Pet\'\n default:\n description: error payload\n content:\n \'text/html\':\n schema:\n $ref: \'#/components/schemas/ErrorModel\'\nparameters:\n- name: id\n in: path\n description: ID of pet to use\n required: true\n schema:\n type: array\n items:\n type: string\n style: simple\n```\n', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, +]; + +export default documentation; diff --git a/packages/apidom-ls/src/config/openapi/path-item/meta.ts b/packages/apidom-ls/src/config/openapi/path-item/meta.ts new file mode 100644 index 0000000000..33a6f79694 --- /dev/null +++ b/packages/apidom-ls/src/config/openapi/path-item/meta.ts @@ -0,0 +1,8 @@ +import documentation from './documentation'; +import { FormatMeta } from '../../../apidom-language-types'; + +const meta: FormatMeta = { + documentation, +}; + +export default meta; diff --git a/packages/apidom-ls/src/config/openapi/paths/documentation.ts b/packages/apidom-ls/src/config/openapi/paths/documentation.ts new file mode 100644 index 0000000000..3201c27023 --- /dev/null +++ b/packages/apidom-ls/src/config/openapi/paths/documentation.ts @@ -0,0 +1,8 @@ +const documentation = [ + { + docs: '#### [Paths Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsObject)\n\nHolds the relative paths to the individual endpoints and their operations. The path is appended to the URL from the [`Server Object`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject) in order to construct the full URL. The Paths MAY be empty, due to [Access Control List (ACL) constraints](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securityFiltering).\n\n##### Patterned Fields\n\nField Pattern | Type | Description\n---|:---:|---\n/{path} | [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject) | A relative path to an individual endpoint. The field name MUST begin with a forward slash (`/`). The path is **appended** (no relative URL resolution) to the expanded URL from the [Server Object\'s](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject) `url` field in order to construct the full URL. [Path templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating) is allowed. When matching URLs, concrete(non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical.In case of ambiguous matching, it is up to the tooling to decide which one to use.\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##### Path Templating Matching\n\n\n\\\nAssuming the following paths, the concrete definition, `/pets/mine`, will be matched first if used:\n\n\n```yaml\n /pets/{petId}\n /pets/mine\n```\n\n\nThe following paths are considered identical and invalid:\n\n\n```yaml\n /pets/{petId}\n /pets/{name}\n```\n\n\nThe following may lead to ambiguous resolution:\n\n```yaml\n /{entity}/me\n /books/{id}\n```\n\n##### Paths Object Example\n\n\n\\\nJSON\n```json\n{\n "/pets": {\n "get": {\n "description": "Returns all pets from the system that the user has access to",\n "responses": {\n "200": {\n "description": "A list of pets.",\n "content": {\n "application/json": {\n "schema": {\n "type": "array",\n "items": {\n "$ref": "#/components/schemas/pet"\n }\n }\n }\n }\n }\n }\n }\n }\n}\n```\n\n\n\\\nYAML\n```yaml\n /pets:\n get:\n description: Returns all pets from the system that the user has access to\n responses:\n \'200\':\n description: A list of pets.\n content:\n application\\/ json:\n schema:\n type: array\n items:\n $ref: \'#/components/schemas/pet\'\n```\n', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, +]; + +export default documentation; diff --git a/packages/apidom-ls/src/config/openapi/paths/meta.ts b/packages/apidom-ls/src/config/openapi/paths/meta.ts new file mode 100644 index 0000000000..33a6f79694 --- /dev/null +++ b/packages/apidom-ls/src/config/openapi/paths/meta.ts @@ -0,0 +1,8 @@ +import documentation from './documentation'; +import { FormatMeta } from '../../../apidom-language-types'; + +const meta: FormatMeta = { + documentation, +}; + +export default meta; diff --git a/packages/apidom-ls/src/config/openapi/responses/documentation.ts b/packages/apidom-ls/src/config/openapi/responses/documentation.ts new file mode 100644 index 0000000000..fd8667a272 --- /dev/null +++ b/packages/apidom-ls/src/config/openapi/responses/documentation.ts @@ -0,0 +1,8 @@ +const documentation = [ + { + docs: '#### [Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responses-object)\n\nA container for the expected responses of an operation. The container maps a HTTP response code to the expected response.\n\n\\\nThe documentation is not necessarily expected to cover all possible HTTP response codes because they may not be known in advance. However, documentation is expected to cover a successful operation response and any known errors.\n\n\\\nThe `default` MAY be used as a default response object for all HTTP codes that are not covered individually by the `Responses Object`.\n\n\\\nThe `Responses Object` MUST contain at least one response code, and if only one response code is provided it SHOULD be the response for a successful operation call.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\ndefault | [Response Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responseObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) | The documentation of responses other than the ones declared for specific HTTP response codes. Use this field to cover undeclared responses.\n\n##### Patterned Fields\n\nField Pattern | Type | Description\n---|:---:|---\n[HTTP Status Code](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#httpCodes) | [Response Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responseObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) | Any [HTTP status code](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#httpCodes) can be used as the property name, but only one property per code, to describe the expected response for that HTTP status code. This field MUST be enclosed in quotation marks (for example, "200") for compatibility between JSON and YAML. To define a range of response codes, this field MAY contain the uppercase wildcard character `X`. For example, `2XX` represents all response codes between `[200-299]`. Only the following range definitions are allowed: `1XX`, `2XX`, `3XX`, `4XX`, and `5XX`. If a response is defined using an explicit code, the explicit code definition takes precedence over the range definition for that code.\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##### Responses Object Example\n\n\n\\\nA 200 response for a successful operation and a default response for others (implying an error):\n\n\\\nJSON\n```json\n{\n "200": {\n "description": "a pet to be returned",\n "content": {\n "application/json": {\n "schema": {\n "$ref": "#/components/schemas/Pet"\n }\n }\n }\n },\n "default": {\n "description": "Unexpected error",\n "content": {\n "application/json": {\n "schema": {\n "$ref": "#/components/schemas/ErrorModel"\n }\n }\n }\n }\n```\n\n\n\\\nYAML\n```yaml\n\'200\':\n description: a pet to be returned\n content:\n application/json:\n schema:\n $ref: \'#/components/schemas/Pet\'\ndefault:\n description: Unexpected error\n content:\n application/json:\n schema:\n $ref: \'#/components/schemas/ErrorModel\'\n```\n', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, +]; + +export default documentation; diff --git a/packages/apidom-ls/src/config/openapi/responses/meta.ts b/packages/apidom-ls/src/config/openapi/responses/meta.ts new file mode 100644 index 0000000000..33a6f79694 --- /dev/null +++ b/packages/apidom-ls/src/config/openapi/responses/meta.ts @@ -0,0 +1,8 @@ +import documentation from './documentation'; +import { FormatMeta } from '../../../apidom-language-types'; + +const meta: FormatMeta = { + documentation, +}; + +export default meta; diff --git a/packages/apidom-ls/src/config/openapi/server-variable/documentation.ts b/packages/apidom-ls/src/config/openapi/server-variable/documentation.ts new file mode 100644 index 0000000000..02a869723d --- /dev/null +++ b/packages/apidom-ls/src/config/openapi/server-variable/documentation.ts @@ -0,0 +1,21 @@ +const documentation = [ + { + target: 'enum', + docs: 'An enumeration of string values to be used if the substitution options are from a limited set. The array MUST NOT be empty.', + }, + { + target: 'default', + docs: "**REQUIRED.** The default value to use for substitution, which SHALL be sent if an alternate value is *not* supplied. Note this behavior is different than the [Schema Object's](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject) treatment of default values, because in those cases parameter values are optional.If the [`enum`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableEnum) is defined, the value MUST exist in the enum's values.", + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + { + target: 'description', + docs: 'An optional description for the server variable. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.', + }, + { + docs: "#### [Server Variable Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableObject)\n\nAn object representing a Server Variable for server URL template substitution.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nenum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set. The array MUST NOT be empty.\ndefault | `string` | **REQUIRED.** The default value to use for substitution, which SHALL be sent if an alternate value is *not* supplied. Note this behavior is different than the [Schema Object's](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject) treatment of default values, because in those cases parameter values are optional.If the [`enum`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableEnum) is defined, the value MUST exist in the enum's values.\ndescription | `string` | An optional description for the server variable. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\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", + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, +]; + +export default documentation; diff --git a/packages/apidom-ls/src/config/openapi/server-variable/meta.ts b/packages/apidom-ls/src/config/openapi/server-variable/meta.ts new file mode 100644 index 0000000000..33a6f79694 --- /dev/null +++ b/packages/apidom-ls/src/config/openapi/server-variable/meta.ts @@ -0,0 +1,8 @@ +import documentation from './documentation'; +import { FormatMeta } from '../../../apidom-language-types'; + +const meta: FormatMeta = { + documentation, +}; + +export default meta; diff --git a/packages/apidom-ls/src/config/openapi/server/documentation.ts b/packages/apidom-ls/src/config/openapi/server/documentation.ts new file mode 100644 index 0000000000..684663e37f --- /dev/null +++ b/packages/apidom-ls/src/config/openapi/server/documentation.ts @@ -0,0 +1,21 @@ +const documentation = [ + { + target: 'url', + docs: '**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 OpenAPI document is being served. Variable substitutions will be made when a variable is named in `{` brackets `}`.', + }, + { + target: 'description', + docs: 'An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.', + }, + { + target: 'variables', + docs: "#### Map[`string`, [Server Variable Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableObject)]\n\nA map between a variable name and its value. The value is used for substitution in the server's URL template.", + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + { + docs: '#### [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)\n\nAn object representing a Server.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nurl | [`string`] | **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 OpenAPI document is being served. Variable substitutions will be made when a variable is named in {brackets}.\ndescription | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nvariables | Map[`string`, [Server Variable Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server URL template.\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##### Server Object Example\n\n\n\\\nA single server would be described as:\n\n\\\nJSON\n```json\n{\n "url": "https://development.gigantic-server.com/v1",\n "description": "Development server"\n}\n```\n\n\n\\\nYAML\n```yaml\nurl: https://development.gigantic-server.com/v1\ndescription: Development server\n```\n\n\\\nThe following shows how multiple servers can be described, for example, at the OpenAPI Object\'s [`servers`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasServers):\n\n\\\nJSON\n```json\n{\n "servers": [\n {\n "url": "https://development.gigantic-server.com/v1",\n "description": "Development server"\n },\n {\n "url": "https://staging.gigantic-server.com/v1",\n "description": "Staging server"\n },\n {\n "url": "https://api.gigantic-server.com/v1",\n "description": "Production server"\n }\n ]\n}\n```\n\n\n\\\nYAML\n```yaml\nservers:\n- url: https://development.gigantic-server.com/v1\n description: Development server\n- url: https://staging.gigantic-server.com/v1\n description: Staging server\n- url: https://api.gigantic-server.com/v1\n description: Production server\n```\n\n\\\nThe following shows how variables can be used for a server configuration:\n\n\\\nJSON\n```json\n{\n "servers": [\n {\n "url": "https://{username}.gigantic-server.com:{port}/{basePath}",\n "description": "The production API server",\n "variables": {\n "username": {\n "default": "demo",\n "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"\n },\n "port": {\n "enum": [\n "8443",\n "443"\n ],\n "default": "8443"\n },\n "basePath": {\n "default": "v2"\n }\n }\n }\n ]\n}\n```\n\n\n\\\nYAML\n```yaml\nservers:\n- url: https://{username}.gigantic-server.com:{port}/{basePath}\n description: The production API server\n variables:\n username:\n # note! no enum here means it is an open value\n default: demo\n description: this value is assigned by the service provider, in this example`gigantic-server.com`\n port:\n enum:\n - \'8443\'\n - \'443\'\n default: \'8443\'\n basePath:\n # open meaning there is the opportunity to use special base paths as assigned by the provider, default is`v2`\n default: v2\n```\n', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, +]; + +export default documentation; diff --git a/packages/apidom-ls/src/config/openapi/server/meta.ts b/packages/apidom-ls/src/config/openapi/server/meta.ts new file mode 100644 index 0000000000..33a6f79694 --- /dev/null +++ b/packages/apidom-ls/src/config/openapi/server/meta.ts @@ -0,0 +1,8 @@ +import documentation from './documentation'; +import { FormatMeta } from '../../../apidom-language-types'; + +const meta: FormatMeta = { + documentation, +}; + +export default meta; diff --git a/packages/apidom-ls/src/config/openapi/tag/documentation.ts b/packages/apidom-ls/src/config/openapi/tag/documentation.ts new file mode 100644 index 0000000000..cd47b66c99 --- /dev/null +++ b/packages/apidom-ls/src/config/openapi/tag/documentation.ts @@ -0,0 +1,22 @@ +const documentation = [ + { target: 'name', docs: '**REQUIRED**. The name of the tag.' }, + { + target: 'description', + docs: 'A description for the tag. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.', + }, + /** + * The following Fixed Field is provided as reference, but is more + * comprehensively described by parent External Documentation Object meta documentation + */ + // { + // target: 'externalDocs', + // docs: '#### [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#externalDocumentationObject)\n\nAdditional external documentation for this operation.', + // targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + // }, + { + docs: '#### [Tag Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#tag-object)\n\nAdds metadata to a single tag that is used by the [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject). It is not mandatory to have a Tag Object per tag defined in the Operation Object instances.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nname | `string` | **REQUIRED**. The name of the tag.\ndescription | `string` | A description for the tag. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nexternalDocs | [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#externalDocumentationObject) | Additional external documentation for this tag.\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##### Tag Object Example\n\n\n\\\nJSON\n```json\n{\n "name": "pet",\n "description": "Pets operations"\n}\n```\n\n\n\\\nYAML\n```yaml\nname: pet\ndescription: Pets operations\n```\n', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, +]; + +export default documentation; diff --git a/packages/apidom-ls/src/config/openapi/tag/meta.ts b/packages/apidom-ls/src/config/openapi/tag/meta.ts new file mode 100644 index 0000000000..33a6f79694 --- /dev/null +++ b/packages/apidom-ls/src/config/openapi/tag/meta.ts @@ -0,0 +1,8 @@ +import documentation from './documentation'; +import { FormatMeta } from '../../../apidom-language-types'; + +const meta: FormatMeta = { + documentation, +}; + +export default meta; diff --git a/packages/apidom-ls/src/config/tokens.ts b/packages/apidom-ls/src/config/tokens.ts index 008f11b7ea..4a52a0f941 100644 --- a/packages/apidom-ls/src/config/tokens.ts +++ b/packages/apidom-ls/src/config/tokens.ts @@ -29,6 +29,9 @@ export default [ 'schema', 'server', 'servers', + 'server-variables', + // 'servers-variables', + // 'serverVariables', 'title', 'channelItem', 'channels',