From 03b3117dee28304de47afbf24505f541c6aba216 Mon Sep 17 00:00:00 2001 From: Timothy Lai Date: Thu, 15 Sep 2022 11:19:40 -0700 Subject: [PATCH] feat(ls): oas31 docs for security scheme object --- .../apidom-ls/src/config/openapi/config.ts | 2 + .../openapi/security-scheme/documentation.ts | 44 +++++++++++++++++++ .../config/openapi/security-scheme/meta.ts | 8 ++++ 3 files changed, 54 insertions(+) create mode 100644 packages/apidom-ls/src/config/openapi/security-scheme/documentation.ts create mode 100644 packages/apidom-ls/src/config/openapi/security-scheme/meta.ts diff --git a/packages/apidom-ls/src/config/openapi/config.ts b/packages/apidom-ls/src/config/openapi/config.ts index 3176998d10..e9bb2ef301 100644 --- a/packages/apidom-ls/src/config/openapi/config.ts +++ b/packages/apidom-ls/src/config/openapi/config.ts @@ -14,6 +14,7 @@ import pathItemMeta from './path-item/meta'; import pathsMeta from './paths/meta'; import responseMeta from './response/meta'; import responsesMeta from './responses/meta'; +import securitySchemeMeta from './security-scheme/meta'; import serverMeta from './server/meta'; import serverVariableMeta from './server-variable/meta'; import tagMeta from './tag/meta'; @@ -51,6 +52,7 @@ export default { paths: pathsMeta, response: responseMeta, responses: responsesMeta, + securityScheme: securitySchemeMeta, server: serverMeta, serverVariable: serverVariableMeta, tag: tagMeta, diff --git a/packages/apidom-ls/src/config/openapi/security-scheme/documentation.ts b/packages/apidom-ls/src/config/openapi/security-scheme/documentation.ts new file mode 100644 index 0000000000..af93eda26d --- /dev/null +++ b/packages/apidom-ls/src/config/openapi/security-scheme/documentation.ts @@ -0,0 +1,44 @@ +const documentation = [ + { + target: 'type', + docs: '##### Applies To\nAny\n\n\\\n**REQUIRED**. The type of the security scheme. Valid values are `"apiKey"`, `"http"`, `"mutualTLS"`, `"oauth2"`, `"openIdConnect"`.', + }, + { + target: 'description', + docs: '##### Applies To\nAny\n\n\\\nA description for security scheme. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.', + }, + { + target: 'name', + docs: '##### Applies To\n`apiKey`\n\n\\\n**REQUIRED**. The name of the header, query or cookie parameter to be used.', + }, + { + target: 'in', + docs: '##### Applies To\n`apiKey`\n\n\\\n**REQUIRED**. The location of the API key. Valid values are `"query"`, `"header"` or `"cookie"`.', + }, + { + target: 'scheme', + docs: '##### Applies To\n`http`\n\n\\\n**REQUIRED**. The name of the HTTP Authorization scheme to be used in the [Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1). The values used SHOULD be registered in the [IANA Authentication Scheme registry](https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml).', + }, + { + target: 'bearerFormat', + docs: '##### Applies To\n`http` (`"bearer"`)\n\n\\\nA hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes.', + }, + { + target: 'openIdConnectUrl', + docs: '##### Applies To\n`openIdConnect`\n\n\\\n**REQUIRED**. OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL. The OpenID Connect standard requires the use of TLS.', + }, + /** The following Fixed Field is provided as reference, but are more + * comprehensively described by parent Server Object meta documentation + */ + // { + // target: 'flows', + // docs: '#### [OAuth Flows Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oauthFlowsObject)\n\##### Applies To\n`oauth2`\n\n\\\n**REQUIRED**. An object containing configuration information for the flow types supported.', + // targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + // }, + { + docs: '#### Security Scheme Object\nDefines a security scheme that can be used by the operations.\n\n\\\nSupported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter), mutual TLS (use of a client certificate), OAuth2\'s common flows(implicit, password, client credentials and authorization code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749), and [OpenID Connect Discovery](https://tools.ietf.org/html/draft-ietf-oauth-discovery-06). Please note that as of 2020, the implicit flow is about to be deprecated by [OAuth 2.0 Security Best Current Practice](https://tools.ietf.org/html/draft-ietf-oauth-security-topics). Recommended for most use case is Authorization Code Grant flow with PKCE.\n\n##### Fixed Fields\n\nField Name | Type | Applies To | Description\n---|:---:|---|:---\ntype | `string` | Any | **REQUIRED**. The type of the security scheme. Valid values are `"apiKey"`, `"http"`, `"mutualTLS"`, `"oauth2"`, `"openIdConnect"`.\ndescription | `string` | Any | A description for security scheme. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nname | `string` | `apiKey` | **REQUIRED**. The name of the header, query or cookie parameter to be used.\nin | `string` | `apiKey` | **REQUIRED**. The location of the API key. Valid values are `"query"`, `"header"` or `"cookie"`.\nscheme | `string` | `http` | **REQUIRED**. The name of the HTTP Authorization scheme to be used in the [Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1). The values used SHOULD be registered in the [IANA Authentication Scheme registry](https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml).\nbearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes.\nflows | [OAuth Flows Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oauthFlowsObject) | `oauth2` | **REQUIRED**. An object containing configuration information for the flow types supported.\nopenIdConnectUrl | `string` | `openIdConnect` | **REQUIRED**. OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL. The OpenID Connect standard requires the use of TLS.\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##### Security Scheme Object Example\nBasic Authentication Sample\n\n\\\nJSON\n```json\n{\n "type": "http",\n "scheme": "basic"\n}\n```\n\n\\\nYAML\n```yaml\ntype: http\nscheme: basic\n```\n\n\\\nAPI Key Sample\n\n\\\nJSON\n```json\n{\n "type": "apiKey",\n "name": "api_key",\n "in": "header"\n}\n```\n\n\\\nYAML\n```yaml\ntype: apiKey\nname: api_key\nin: header\n```\n\n\\\nJWT Bearer Sample\n\n\\\nJSON\n```json\n{\n "type": "http",\n "scheme": "bearer",\n "bearerFormat": "JWT",\n}\n```\n\n\\\nYAML\n```yaml\ntype: http\nscheme: bearer\nbearerFormat: JWT\n```\n\n\\\nImplicit OAuth2 Sample\n\n\\\nJSON\n```json\n{\n "type": "oauth2",\n "flows": {\n "implicit": {\n "authorizationUrl": "https://example.com/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\\\nYAML\n```yaml\ntype: oauth2\nflows: \n implicit:\n authorizationUrl: https://example.com/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/security-scheme/meta.ts b/packages/apidom-ls/src/config/openapi/security-scheme/meta.ts new file mode 100644 index 0000000000..33a6f79694 --- /dev/null +++ b/packages/apidom-ls/src/config/openapi/security-scheme/meta.ts @@ -0,0 +1,8 @@ +import documentation from './documentation'; +import { FormatMeta } from '../../../apidom-language-types'; + +const meta: FormatMeta = { + documentation, +}; + +export default meta;