From 8c945921342ef9a594bab1de7fc4e5fd68804b0b Mon Sep 17 00:00:00 2001 From: Timothy Lai Date: Fri, 16 Sep 2022 10:59:26 -0700 Subject: [PATCH] feat(ls): oas31 docs for components object --- .../openapi/components/documentation.ts | 59 +++++++++++++++++++ .../src/config/openapi/components/meta.ts | 8 +++ .../apidom-ls/src/config/openapi/config.ts | 3 +- 3 files changed, 69 insertions(+), 1 deletion(-) create mode 100644 packages/apidom-ls/src/config/openapi/components/documentation.ts create mode 100644 packages/apidom-ls/src/config/openapi/components/meta.ts diff --git a/packages/apidom-ls/src/config/openapi/components/documentation.ts b/packages/apidom-ls/src/config/openapi/components/documentation.ts new file mode 100644 index 0000000000..cb40623a51 --- /dev/null +++ b/packages/apidom-ls/src/config/openapi/components/documentation.ts @@ -0,0 +1,59 @@ +const documentation = [ + // dev note: although, these types are all Maps[`string`, Object] + { + target: 'schemas', + docs: 'Map[`string`, [Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject)]\n\nAn object to hold reusable [Schema Objects](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject).', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + { + target: 'responses', + docs: 'Map[`string`, [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)]\n\nAn object to hold reusable [Response Objects](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responseObject).', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + { + target: 'parameters', + docs: 'Map[`string`, [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\nAn object to hold reusable [Parameter Objects](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject).', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + { + 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\nAn object to hold reusable [Example Objects](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#exampleObject).', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + { + target: 'requestBodies', + docs: 'Map[`string`, [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\nAn object to hold reusable [Request Body Objects](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#requestBodyObject).', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + { + target: 'headers', + docs: 'Map[`string`, [Header Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#headerObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]\n\nAn object to hold reusable [Header Objects](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#headerObject).', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + { + target: 'securitySchemes', + docs: 'Map[`string`, [Security Scheme Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securitySchemeObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]\n\nAn object to hold reusable [Security Scheme Objects](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securitySchemeObject).', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + { + target: 'links', + docs: 'Map[`string`, [Link Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#linkObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]\n\nAn object to hold reusable [Link Objects](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#linkObject).', + 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\nAn object to hold reusable [Callback Objects](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject).', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + { + target: 'pathItems', + 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\nAn object to hold reusable [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject).', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + { + docs: '#### Components Object\nHolds a set of reusable objects for different aspects of the OAS. All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nschemas | Map[`string`, [Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject)] | An object to hold reusable [Schema Objects](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject).\nresponses | Map[`string`, [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)] | An object to hold reusable [Response Objects](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responseObject).\nparameters | Map[`string`, [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)] | An object to hold reusable [Parameter Objects](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject).\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)] | An object to hold reusable [Example Objects](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#exampleObject).\nrequestBodies | Map[`string`, [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)] | An object to hold reusable [Request Body Objects](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#requestBodyObject).\nheaders | Map[`string`, [Header Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#headerObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | An object to hold reusable [Header Objects](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#headerObject).\nsecuritySchemes | Map[`string`, [Security Scheme Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securitySchemeObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | An object to hold reusable [Security Scheme Objects](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securitySchemeObject).\nlinks | Map[`string`, [Link Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#linkObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | An object to hold reusable [Link Objects](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#linkObject).\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)] | An object to hold reusable [Callback Objects](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject).\npathItems | 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)] | An object to hold reusable [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject).\n\n\\\nThis object MAY be extended with Specification Extensions.\n\n\\\nAll the fixed fields declared above are objects that MUST use keys that match the regular expression: `^[a-zA-Z0-9\\.\\-_]+$`.\n\n\\\nField Name Examples:\n\n\\\nYAML\n```yaml\nUser\nUser_1\nUser_Name\nuser-name\nmy.org.User\n```\n\n##### Components Object Example\n\n\\\nJSON\n```json\n"components": {\n "schemas": {\n "GeneralError": {\n "type": "object",\n "properties": {\n "code": {\n "type": "integer",\n "format": "int32"\n },\n "message": {\n "type": "string"\n }\n }\n },\n "Category": {\n "type": "object",\n "properties": {\n "id": {\n "type": "integer",\n "format": "int64"\n },\n "name": {\n "type": "string"\n }\n }\n },\n "Tag": {\n "type": "object",\n "properties": {\n "id": {\n "type": "integer",\n "format": "int64"\n },\n "name": {\n "type": "string"\n }\n }\n }\n },\n "parameters": {\n "skipParam": {\n "name": "skip",\n "in": "query",\n "description": "number of items to skip",\n "required": true,\n "schema": {\n "type": "integer",\n "format": "int32"\n }\n },\n "limitParam": {\n "name": "limit",\n "in": "query",\n "description": "max records to return",\n "required": true,\n "schema" : {\n "type": "integer",\n "format": "int32"\n }\n }\n },\n "responses": {\n "NotFound": {\n "description": "Entity not found."\n },\n "IllegalInput": {\n "description": "Illegal input for operation."\n },\n "GeneralError": {\n "description": "General Error",\n "content": {\n "application/json": {\n "schema": {\n "$ref": "#/components/schemas/GeneralError"\n }\n }\n }\n }\n },\n "securitySchemes": {\n "api_key": {\n "type": "apiKey",\n "name": "api_key",\n "in": "header"\n },\n "petstore_auth": {\n "type": "oauth2",\n "flows": {\n "implicit": {\n "authorizationUrl": "https://example.org/api/oauth/dialog",\n "scopes": {\n "write:pets": "modify pets in your account",\n "read:pets": "read your pets"\n }\n }\n }\n }\n }\n}\n```\n\n\\\nYAML\n```yaml\ncomponents:\n schemas:\n GeneralError:\n type: object\n properties:\n code:\n type: integer\n format: int32\n message:\n type: string\n Category:\n type: object\n properties:\n id:\n type: integer\n format: int64\n name:\n type: string\n Tag:\n type: object\n properties:\n id:\n type: integer\n format: int64\n name:\n type: string\n parameters:\n skipParam:\n name: skip\n in: query\n description: number of items to skip\n required: true\n schema:\n type: integer\n format: int32\n limitParam:\n name: limit\n in: query\n description: max records to return\n required: true\n schema:\n type: integer\n format: int32\n responses:\n NotFound:\n description: Entity not found.\n IllegalInput:\n description: Illegal input for operation.\n GeneralError:\n description: General Error\n content:\n application/json:\n schema:\n $ref: \'#/components/schemas/GeneralError\'\n securitySchemes:\n api_key:\n type: apiKey\n name: api_key\n in: header\n petstore_auth:\n type: oauth2\n flows: \n implicit:\n authorizationUrl: https://example.org/api/oauth/dialog\n scopes:\n write:pets: modify pets in your account\n read:pets: read your pets\n```\n', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, +]; + +export default documentation; diff --git a/packages/apidom-ls/src/config/openapi/components/meta.ts b/packages/apidom-ls/src/config/openapi/components/meta.ts new file mode 100644 index 0000000000..33a6f79694 --- /dev/null +++ b/packages/apidom-ls/src/config/openapi/components/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/config.ts b/packages/apidom-ls/src/config/openapi/config.ts index 20d9985ea7..dd71a1b72e 100644 --- a/packages/apidom-ls/src/config/openapi/config.ts +++ b/packages/apidom-ls/src/config/openapi/config.ts @@ -1,4 +1,5 @@ import callbackMeta from './callback/meta'; +import componentsMeta from './components/meta'; import contactMeta from './contact/meta'; import exampleMeta from './example/meta'; import externalDocumentationMeta from './external-documentation/meta'; @@ -37,6 +38,7 @@ export default { ], }, callback: callbackMeta, + components: componentsMeta, contact: contactMeta, example: exampleMeta, externalDocumentation: externalDocumentationMeta, @@ -48,7 +50,6 @@ export default { oAuthFlows: oauthFlowsMeta, operation: operationMeta, parameter: parameterMeta, - parameters: parameterMeta, pathItem: pathItemMeta, paths: pathsMeta, response: responseMeta,