feat(ls): docs for OpenApi 3.1.0 Security Scheme object

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,

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;

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;