Skip to content

Commit 8eb948a

Browse files
authored
feat(ls): add rules for OpenAPI 2.0 Responses Object (#3664)
Refs #3606
1 parent 8c86d48 commit 8eb948a

File tree

6 files changed

+55
-8
lines changed

6 files changed

+55
-8
lines changed

packages/apidom-ls/src/config/openapi/responses/completion.ts

+15-1
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ import {
33
CompletionFormat,
44
CompletionType,
55
} from '../../../apidom-language-types';
6-
import { OpenAPI30, OpenAPI31 } from '../target-specs';
6+
import { OpenAPI2, OpenAPI30, OpenAPI31 } from '../target-specs';
77

88
// eslint-disable-next-line @typescript-eslint/naming-convention
99
const httpCode3_0CompletionItem = {
@@ -34,6 +34,20 @@ const httpCode3_1CompletionRule = {
3434
};
3535

3636
const completion: ApidomCompletionItem[] = [
37+
{
38+
label: 'default',
39+
insertText: 'default',
40+
kind: 14,
41+
format: CompletionFormat.OBJECT,
42+
type: CompletionType.PROPERTY,
43+
insertTextFormat: 2,
44+
documentation: {
45+
kind: 'markdown',
46+
value:
47+
"[Response Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#responseObject) \\| [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#referenceObject)\n\\\n\\\nThe documentation of responses other than the ones declared for specific HTTP response codes. It can be used to cover undeclared responses. [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#referenceObject) can be used to link to a response that is defined at the [Swagger Object's responses](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#swaggerResponses) section.",
48+
},
49+
targetSpecs: OpenAPI2,
50+
},
3751
{
3852
label: 'default',
3953
insertText: 'default',

packages/apidom-ls/src/config/openapi/responses/documentation.ts

+5-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
1-
import { OpenAPI30, OpenAPI31 } from '../target-specs';
1+
import { OpenAPI2, OpenAPI30, OpenAPI31 } from '../target-specs';
22

33
const documentation = [
4+
{
5+
docs: '#### [Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#responses-object)\n\nA container for the expected responses of an operation. The container maps a HTTP response code to the expected response. It is not expected from the documentation to necessarily cover all possible HTTP response codes, since they may not be known in advance. However, it is expected from the documentation to cover a successful operation response and any known errors.\n\nThe `default` can be used as the default response object for all HTTP codes that are not covered individually by the specification.\n\nThe `Responses Object` MUST contain at least one response code, and it SHOULD be the response for a successful operation call.\n\n##### Fixed Fields\nField Name | Type | Description\n---|:---:|---\ndefault | [Response Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#responseObject) \\| [Reference Object](#referenceObject) | The documentation of responses other than the ones declared for specific HTTP response codes. It can be used to cover undeclared responses. [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#referenceObject) can be used to link to a response that is defined at the [Swagger Object\'s responses](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#swaggerResponses) section.\n\n##### Patterned Fields\nField Pattern | Type | Description\n---|:---:|---\n{[HTTP Status Code](#httpCodes)} | [Response Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#responseObject) \\| [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#referenceObject) | Any [HTTP status code](#httpCodes) can be used as the property name (one property per HTTP status code). Describes the expected response for that HTTP status code. [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#referenceObject) can be used to link to a response that is defined at the [Swagger Object\'s responses](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#swaggerResponses) section.\n^x- | Any | Allows extensions to the Swagger Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Vendor Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#vendorExtensions) for further details.\n\n\n##### Responses Object Example\n\nA 200 response for successful operation and a default response for others (implying an error):\n\n```js\n{\n "200": {\n "description": "a pet to be returned",\n "schema": {\n "$ref": "#/definitions/Pet"\n }\n },\n "default": {\n "description": "Unexpected error",\n "schema": {\n "$ref": "#/definitions/ErrorModel"\n }\n }\n}\n```\n\n\n\\\nYAML\n```yaml\n\'200\':\n description: a pet to be returned\n schema:\n $ref: \'#/definitions/Pet\'\ndefault:\n description: Unexpected error\n schema:\n $ref: \'#/definitions/ErrorModel\'\n```',
6+
targetSpecs: OpenAPI2,
7+
},
48
{
59
docs: '#### [Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#responses-object)\n\nA container for the expected responses of an operation.\nThe container maps a HTTP response code to the expected response.\n\nThe documentation is not necessarily expected to cover all possible HTTP response codes because they may not be known in advance.\nHowever, documentation is expected to cover a successful operation response and any known errors.\n\nThe `default` MAY be used as a default response object for all HTTP codes\nthat are not covered individually by the specification.\n\nThe `Responses Object` MUST contain at least one response code, and it\nSHOULD be the response for a successful operation call.\n\n##### Fixed Fields\nField Name | Type | Description\n---|:---:|---\ndefault | [Response Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#responseObject) \\| [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#referenceObject) | The documentation of responses other than the ones declared for specific HTTP response codes. Use this field to cover undeclared responses. A [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#referenceObject) can link to a response that the [OpenAPI Object\'s components/responses](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#componentsResponses) section defines.\n\n##### Patterned Fields\nField Pattern | Type | Description\n---|:---:|---\n[HTTP Status Code](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#httpCodes) | [Response Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#responseObject) \\| [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#referenceObject) | Any [HTTP status code](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#httpCodes) can be used as the property name, but only one property per code, to describe the expected response for that HTTP status code. A [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#referenceObject) can link to a response that is defined in the [OpenAPI Object\'s components/responses](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#componentsResponses) section. This field MUST be enclosed in quotation marks (for example, "200") for compatibility between JSON and YAML. To define a range of response codes, this field MAY contain the uppercase wildcard character `X`. For example, `2XX` represents all response codes between `[200-299]`. Only the following range definitions are allowed: `1XX`, `2XX`, `3XX`, `4XX`, and `5XX`. If a response is defined using an explicit code, the explicit code definition takes precedence over the range definition for that code.\n\n\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specificationExtensions).\n\n##### Responses Object Example\n\nA 200 response for a successful operation and a default response for others (implying an error):\n\n\n\\\nJSON\n```json\n{\n "200": {\n "description": "a pet to be returned",\n "content": {\n "application/json": {\n "schema": {\n "$ref": "#/components/schemas/Pet"\n }\n }\n }\n },\n "default": {\n "description": "Unexpected error",\n "content": {\n "application/json": {\n "schema": {\n "$ref": "#/components/schemas/ErrorModel"\n }\n }\n }\n }\n}\n```\n\n\n\\\nYAML\n```yaml\n\'200\':\n description: a pet to be returned\n content:\n application/json:\n schema:\n $ref: \'#/components/schemas/Pet\'\ndefault:\n description: Unexpected error\n content:\n application/json:\n schema:\n $ref: \'#/components/schemas/ErrorModel\'\n```',
610
targetSpecs: OpenAPI30,
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
import { range } from 'ramda';
2+
import { DiagnosticSeverity } from 'vscode-languageserver-types';
3+
4+
import ApilintCodes from '../../../codes';
5+
import { LinterMeta } from '../../../../apidom-language-types';
6+
import { OpenAPI2 } from '../../target-specs';
7+
8+
/**
9+
* Validation here is based on IANA HTTP Status code registry: https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
10+
*
11+
* Clarification of OpenAPI specification what are accepted HTTP Status code comes from https://github.com/OAI/OpenAPI-Specification/issues/2471.
12+
*/
13+
14+
// eslint-disable-next-line @typescript-eslint/naming-convention
15+
const allowedFields2_0Lint: LinterMeta = {
16+
code: ApilintCodes.NOT_ALLOWED_FIELDS,
17+
source: 'apilint',
18+
message:
19+
'Responses Object uses HTTP Status Codes outside of allowed IANA HTTP Status code registry',
20+
severity: DiagnosticSeverity.Error,
21+
linterFunction: 'allowedFields',
22+
linterParams: [['default', ...range(100, 600).map(String)], 'x-'],
23+
marker: 'key',
24+
targetSpecs: OpenAPI2,
25+
};
26+
27+
export default allowedFields2_0Lint;

packages/apidom-ls/src/config/openapi/responses/lint/allowed-fields.ts renamed to packages/apidom-ls/src/config/openapi/responses/lint/allowed-fields-3-0--3-1.ts

+3-2
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,8 @@ import { OpenAPI3 } from '../../target-specs';
1111
* Clarification of OpenAPI specification what are accepted HTTP Status code comes from https://github.com/OAI/OpenAPI-Specification/issues/2471.
1212
*/
1313

14-
const allowedFieldsLint: LinterMeta = {
14+
// eslint-disable-next-line @typescript-eslint/naming-convention
15+
const allowedFields3_0__3_1Lint: LinterMeta = {
1516
code: ApilintCodes.NOT_ALLOWED_FIELDS,
1617
source: 'apilint',
1718
message:
@@ -26,4 +27,4 @@ const allowedFieldsLint: LinterMeta = {
2627
targetSpecs: OpenAPI3,
2728
};
2829

29-
export default allowedFieldsLint;
30+
export default allowedFields3_0__3_1Lint;
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
1-
import allowedFieldsLint from './allowed-fields';
1+
import allowedFields2_0Lint from './allowed-fields-2-0';
2+
import allowedFields3_0__3_1Lint from './allowed-fields-3-0--3-1';
23
import valuesTypeLint from './values--type';
34

4-
const lints = [valuesTypeLint, allowedFieldsLint];
5+
const lints = [valuesTypeLint, allowedFields2_0Lint, allowedFields3_0__3_1Lint];
56

67
export default lints;

packages/apidom-ls/src/config/openapi/responses/lint/values--type.ts

+2-2
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ import { DiagnosticSeverity } from 'vscode-languageserver-types';
22

33
import ApilintCodes from '../../../codes';
44
import { LinterMeta } from '../../../../apidom-language-types';
5-
import { OpenAPI3 } from '../../target-specs';
5+
import { OpenAPI2, OpenAPI3 } from '../../target-specs';
66

77
const valuesTypeLint: LinterMeta = {
88
code: ApilintCodes.OPENAPI3_0_RESPONSES_VALUES_TYPE,
@@ -13,7 +13,7 @@ const valuesTypeLint: LinterMeta = {
1313
linterParams: [['response']],
1414
marker: 'key',
1515
data: {},
16-
targetSpecs: OpenAPI3,
16+
targetSpecs: [...OpenAPI2, ...OpenAPI3],
1717
};
1818

1919
export default valuesTypeLint;

0 commit comments

Comments
 (0)