Skip to content

fix(ls): fix docs rules for various OpenAPI 3.1.0 objects #2022

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 16, 2022
Merged

fix(ls): fix docs rules for various OpenAPI 3.1.0 objects #2022

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 8 additions & 5 deletions packages/apidom-ls/src/config/openapi/oauth-flow/documentation.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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' }],
},
];
Expand Down
35 changes: 17 additions & 18 deletions packages/apidom-ls/src/config/openapi/security-scheme/documentation.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,42 +1,41 @@
const documentation = [
{
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The changes in this file make this docs rules consistent with AsyncAPI docs rules.

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',
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FIeld description contains significant information - the field is REQUIRED

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' }],
},
];
Expand Down