Skip to content

Commit 0517cfb

Browse files
char0nchar0n
committed
feat(ls): provide OpenAPI 3.0.x Header docs rules
Refs #2031
1 parent 5558ed9 commit 0517cfb

File tree

1 file changed

+54
-3
lines changed

1 file changed

+54
-3
lines changed

‎packages/apidom-ls/src/config/openapi/header/documentation.ts

Lines changed: 54 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,12 @@
1+
/**
2+
* Omitted fixed fields for OpenAPI 3.1.0:
3+
* - schema
4+
*
5+
* Field omission reason: omitted fields do have a non-union type. Thus,
6+
* documentation for these fields doesn't need to be specified here and will
7+
* come directly from the type itself. Description of these fields doesn't
8+
* contain significant information.
9+
*/
110
const documentation = [
211
{
312
target: 'description',
@@ -6,15 +15,14 @@ const documentation = [
615
{
716
target: 'required',
817
docs: 'Determines whether this header is mandatory. This property MAY be included and its default value is `false`.',
9-
targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
1018
},
1119
{
1220
target: 'deprecated',
1321
docs: 'Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is `false`.',
1422
},
1523
{
1624
target: 'allowEmptyValue',
17-
docs: 'Sets the ability to pass empty-valued headers. Default value is `false`. If [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle) is used, and if behavior is `n/a` (cannot be serialized), the value of `allowEmptyValue` SHALL be ignored. Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision.',
25+
docs: "Doesn't apply for headers. Default value is `false`. Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision.",
1826
targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
1927
},
2028
{
@@ -24,21 +32,64 @@ const documentation = [
2432
{
2533
target: 'explode',
2634
docs: 'When this is true, header values of type array or object generate separate headers for each value of the array or key-value pair of the map. The default value is `false`.',
27-
targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
2835
},
2936
{
3037
target: 'allowReserved',
3138
docs: "Determines whether the header value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&'()*+,;=` to be included without percent - encoding. This property has no effect and the default value is `false`.",
3239
},
40+
{
41+
target: 'schema',
42+
docs: '[Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#schemaObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#referenceObject)\n\\\n\\\nThe schema defining the type used for the parameter.',
43+
targetSpecs: [
44+
{ namespace: 'openapi', version: '3.0.0' },
45+
{ namespace: 'openapi', version: '3.0.1' },
46+
{ namespace: 'openapi', version: '3.0.2' },
47+
{ namespace: 'openapi', version: '3.0.3' },
48+
],
49+
},
3350
{
3451
target: 'example',
3552
docs: "Example of the header's potential value. The example SHOULD match the specified schema and encoding properties if present. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` that contains an example, the `example` value SHALL *override* the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.",
3653
},
54+
{
55+
target: 'examples',
56+
docs: "Map[`string`, [Example Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#exampleObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#referenceObject)]\n\\\n\\\nExamples of the parameter's potential value. Each example SHOULD contain a value in the correct format as specified in the header encoding. The `examples` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` that contains an example, the `examples` value SHALL *override* the example provided by the schema",
57+
targetSpecs: [
58+
{ namespace: 'openapi', version: '3.0.0' },
59+
{ namespace: 'openapi', version: '3.0.1' },
60+
{ namespace: 'openapi', version: '3.0.2' },
61+
{ namespace: 'openapi', version: '3.0.3' },
62+
],
63+
},
3764
{
3865
target: 'examples',
3966
docs: "Map[`string`, [Example Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#exampleObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]\n\\\n\\\nExamples of the parameter's potential value. Each example SHOULD contain a value in the correct format as specified in the header encoding. The `examples` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` that contains an example, the `examples` value SHALL *override* the example provided by the schema",
4067
targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
4168
},
69+
{
70+
target: 'content',
71+
docs: 'Map[string, [Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#mediaTypeObject)]\n\\\n\\\nA map containing the representations for the parameter. The key is the media type and the value describes it. The map MUST only contain one entry.',
72+
targetSpecs: [
73+
{ namespace: 'openapi', version: '3.0.0' },
74+
{ namespace: 'openapi', version: '3.0.1' },
75+
{ namespace: 'openapi', version: '3.0.2' },
76+
{ namespace: 'openapi', version: '3.0.3' },
77+
],
78+
},
79+
{
80+
target: 'content',
81+
docs: 'Map[string, [Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject)]\n\\\n\\\nA map containing the representations for the parameter. The key is the media type and the value describes it. The map MUST only contain one entry.',
82+
targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
83+
},
84+
{
85+
docs: '#### [Header Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#headerObject)\n\nThe Header Object follows the structure of the [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameterObject) with the following changes:\n\n1. `name` MUST NOT be specified, it is given in the corresponding `headers` map.\n1. `in` MUST NOT be specified, it is implicitly in `header`.\n1. All traits that are affected by the location MUST be applicable to a location of `header` (for example, [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameterStyle)).\n\n##### Header Object Example\n\nA simple header of type `integer`:\n\n\n\\\nJSON\n```json\n{\n "description": "The number of allowed requests in the current period",\n "schema": {\n "type": "integer"\n }\n}\n```\n\n\n\\\nYAML\n```yaml\ndescription: The number of allowed requests in the current period\nschema:\n type: integer\n```',
86+
targetSpecs: [
87+
{ namespace: 'openapi', version: '3.0.0' },
88+
{ namespace: 'openapi', version: '3.0.1' },
89+
{ namespace: 'openapi', version: '3.0.2' },
90+
{ namespace: 'openapi', version: '3.0.3' },
91+
],
92+
},
4293
{
4394
docs: '#### [Header Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#headerObject)\n\nThe Header Object follows the structure of the [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) with the following changes:\n\n 1. `name` MUST NOT be specified, it is given in the corresponding `headers` map.\n 2. `in` MUST NOT be specified, it is implicitly in `header`.\n 3. All traits that are affected by the location MUST be applicable to a location of `header` (for example, [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle)).\n\n##### Header Object Example\n\n\\\nA simple header of type `integer`:\n\n\\\nJSON\n```json\n{\n "description": "The number of allowed requests in the current period",\n "schema": {\n "type": "integer"\n }\n}\n```\n\n\\\nYAML\n```yaml\ndescription: The number of allowed requests in the current period\nschema:\n type: integer\n```\n',
4495
targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],

0 commit comments

Comments
 (0)