From d20bbd490634c49c26a8d1eea169c27b96ddb63a Mon Sep 17 00:00:00 2001 From: Vladimir Gorej Date: Fri, 16 Sep 2022 11:58:21 +0200 Subject: [PATCH] fix(ls): fix docs rules for various OpenAPI 3.1.0 objects --- .../openapi/oauth-flow/documentation.ts | 13 ++++--- .../openapi/security-scheme/documentation.ts | 35 +++++++++---------- 2 files changed, 25 insertions(+), 23 deletions(-) diff --git a/packages/apidom-ls/src/config/openapi/oauth-flow/documentation.ts b/packages/apidom-ls/src/config/openapi/oauth-flow/documentation.ts index 5a87f00b17..029b5664d2 100644 --- a/packages/apidom-ls/src/config/openapi/oauth-flow/documentation.ts +++ b/packages/apidom-ls/src/config/openapi/oauth-flow/documentation.ts @@ -1,22 +1,25 @@ const documentation = [ { target: 'authorizationUrl', - docs: '##### Applies To\n`oauth2` (`"implicit"`, `"authorizationCode"`)\n\n\\\n**REQUIRED**. The authorization URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.', + docs: 'Applies to `oauth2` (`"implicit"`, `"authorizationCode"`). **REQUIRED**. The authorization URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], }, { target: 'tokenUrl', - docs: '##### Applies To\n`oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`)\n\n\\\n**REQUIRED**. The token URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.', + docs: 'Applies to `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`). **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], }, { target: 'refreshUrl', - docs: '##### Applies To\n`oauth2`\n\n\\\nThe URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.', + docs: 'Applies to `oauth2`. The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], }, { target: 'scopes', - docs: 'Map[`string`, `string`]\n##### Applies To\noauth2\n\n\\\n**REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. The map MAY be empty.', + docs: 'Map[`string`, `string`]\n\nApplies to `oauth2`. **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. The map MAY be empty.', }, { - docs: '#### OAuth Flow Object\nConfiguration details for a supported OAuth Flow\n##### Fixed Fields\nField Name | Type | Applies To | Description\n---|:---:|---|:---\nauthorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **REQUIRED**. The authorization URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.\ntokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.\nrefreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.\nscopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. The map MAY be empty.\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##### OAuth Flow Object Examples\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 "authorizationCode": {\n "authorizationUrl": "https://example.com/api/oauth/dialog",\n "tokenUrl": "https://example.com/api/oauth/token",\n "scopes": {\n "write:pets": "modify pets in your account",\n "read:pets": "read your pets"\n }\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 authorizationCode:\n authorizationUrl: https://example.com/api/oauth/dialog\n tokenUrl: https://example.com/api/oauth/token\n scopes:\n write:pets: modify pets in your account\n read:pets: read your pets\n```\n', + docs: '#### OAuth Flow Object\n\nConfiguration details for a supported OAuth Flow\n##### Fixed Fields\nField Name | Type | Applies To | Description\n---|:---:|---|:---\nauthorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **REQUIRED**. The authorization URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.\ntokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.\nrefreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.\nscopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. The map MAY be empty.\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##### OAuth Flow Object Examples\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 "authorizationCode": {\n "authorizationUrl": "https://example.com/api/oauth/dialog",\n "tokenUrl": "https://example.com/api/oauth/token",\n "scopes": {\n "write:pets": "modify pets in your account",\n "read:pets": "read your pets"\n }\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 authorizationCode:\n authorizationUrl: https://example.com/api/oauth/dialog\n tokenUrl: https://example.com/api/oauth/token\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' }], }, ]; diff --git a/packages/apidom-ls/src/config/openapi/security-scheme/documentation.ts b/packages/apidom-ls/src/config/openapi/security-scheme/documentation.ts index af93eda26d..1a2854a823 100644 --- a/packages/apidom-ls/src/config/openapi/security-scheme/documentation.ts +++ b/packages/apidom-ls/src/config/openapi/security-scheme/documentation.ts @@ -1,42 +1,41 @@ 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"`.', + docs: '**REQUIRED**. The type of the security scheme. Valid values are `"apiKey"`, `"http"`, `"mutualTLS"`, `"oauth2"`, `"openIdConnect"`.', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], }, { 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.', + docs: 'A 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.', + docs: 'Applies to `apiKey`. **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"`.', + docs: 'Applies to `apiKey`. **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).', + docs: 'Applies to `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).', }, { 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.', + docs: 'Applies to `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.', + }, + { + target: 'flows', + docs: '#### [OAuth Flows Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oauthFlowsObject)\\n\\nApplies to `oauth2`. **REQUIRED**. An object containing configuration information for the flow types supported.', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], }, { 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', + docs: 'Applies to `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.', + targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], + }, + { + docs: '#### Security Scheme Object\n\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' }], }, ];