From 76450999d5b3100df1916cbe1c65c3d25b9c0dc2 Mon Sep 17 00:00:00 2001 From: Timothy Lai Date: Tue, 20 Sep 2022 15:41:30 -0700 Subject: [PATCH] feat(ls): docs for OpenApi 3.1.0 Discriminator object --- .../apidom-ls/src/config/openapi/config.ts | 2 ++ .../openapi/discriminator/documentation.ts | 23 +++++++++++++++++++ .../src/config/openapi/discriminator/meta.ts | 8 +++++++ 3 files changed, 33 insertions(+) create mode 100644 packages/apidom-ls/src/config/openapi/discriminator/documentation.ts create mode 100644 packages/apidom-ls/src/config/openapi/discriminator/meta.ts diff --git a/packages/apidom-ls/src/config/openapi/config.ts b/packages/apidom-ls/src/config/openapi/config.ts index 15e2828c04..2f07c306d8 100644 --- a/packages/apidom-ls/src/config/openapi/config.ts +++ b/packages/apidom-ls/src/config/openapi/config.ts @@ -1,6 +1,7 @@ import callbackMeta from './callback/meta'; import componentsMeta from './components/meta'; import contactMeta from './contact/meta'; +import discriminatorMeta from './discriminator/meta'; import encodingMeta from './encoding/meta'; import exampleMeta from './example/meta'; import externalDocumentationMeta from './external-documentation/meta'; @@ -44,6 +45,7 @@ export default { callback: callbackMeta, components: componentsMeta, contact: contactMeta, + discriminator: discriminatorMeta, encoding: encodingMeta, example: exampleMeta, externalDocumentation: externalDocumentationMeta, diff --git a/packages/apidom-ls/src/config/openapi/discriminator/documentation.ts b/packages/apidom-ls/src/config/openapi/discriminator/documentation.ts new file mode 100644 index 0000000000..ade95af288 --- /dev/null +++ b/packages/apidom-ls/src/config/openapi/discriminator/documentation.ts @@ -0,0 +1,23 @@ +const documentation = [ + { + target: 'propertyName', + docs: '**REQUIRED**. The name of the property in the payload that will hold the discriminator value.', + }, + { + target: 'mapping', + docs: 'Map[`string`, `string`]\n\\\n\\\nAn object to hold mappings between payload values and schema names or references.', + }, + { + /** + * The original documentation has been trimmed in this implementation for readability purposes + * A new custom section `Additional documentation topics` has been added, + * which refers the reader to the source documentation for additional explanations + * Also note, we are cherry picking the documentation section about + * `Composition and Inheritance (Polymorphism)`from outside of the Discriminator Object + * source documentation. + */ + docs: '#### [Discriminator Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#discriminator-object)\n\nWhen request bodies or response payloads may be one of a number of different schemas, a `discriminator` object can be used to aid in serialization, deserialization, and validation. The discriminator is a specific object in a schema which is used to inform the consumer of the document of an alternative schema based on the value associated with it.\n\n\\\nWhen using the discriminator, _inline_ schemas will not be considered.\n\n##### Fixed Fields\nField Name | Type | Description\n---|:---:|---\npropertyName | `string` | **REQUIRED**. The name of the property in the payload that will hold the discriminator value.\nmapping | Map[`string`, `string`] | An object to hold mappings between payload values and schema names or references.\n\n\\\nThis object MAY be extended with [Specification Extensions](#specificationExtensihttps://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n\\\nThe discriminator object is legal only when using one of the composite keywords `oneOf`, `anyOf`, `allOf`.\n\n##### [Composition and Inheritance (Polymorphism)](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#composition-and-inheritance-polymorphism)\n\nThe OpenAPI Specification allows combining and extending model definitions using the `allOf` property of JSON Schema, in effect offering model composition.\n`allOf` takes an array of object definitions that are validated *independently* but together compose a single object.\n\n\\\nWhile composition offers model extensibility, it does not imply a hierarchy between the models.\nTo support polymorphism, the OpenAPI Specification adds the `discriminator` field.\nWhen used, the `discriminator` will be the name of the property that decides which schema definition validates the structure of the model.\nAs such, the `discriminator` field MUST be a required field.\nThere are two ways to define the value of a discriminator for an inheriting instance.\n- Use the schema name.\n- Override the schema name by overriding the property with a new value. If a new value exists, this takes precedence over the schema name.\nAs such, inline schema definitions, which do not have a given id, *cannot* be used in polymorphism.\n\n#### Additional documentation topics\n\nFurther explanations of usage can be found in the source documentation for the [Discriminator Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#discriminator-object)\n', + }, +]; + +export default documentation; diff --git a/packages/apidom-ls/src/config/openapi/discriminator/meta.ts b/packages/apidom-ls/src/config/openapi/discriminator/meta.ts new file mode 100644 index 0000000000..33a6f79694 --- /dev/null +++ b/packages/apidom-ls/src/config/openapi/discriminator/meta.ts @@ -0,0 +1,8 @@ +import documentation from './documentation'; +import { FormatMeta } from '../../../apidom-language-types'; + +const meta: FormatMeta = { + documentation, +}; + +export default meta;