Skip to content

Commit af4cc38

Browse files
TimvdLippeTimvdLippe
committed
Sta expliciet niet toe dat query keys met een getal beginnen
Er zijn in het API register ook geen API's die dit hebben. Bij het afgelopen TO is gevraagd om deze verscherping. Tevens is de linter regel weer toegevoegd. Die is onverhoopt bij het mergen van de vorige PR verdwenen. Nu staat hij er weer, inclusief wat test cases.
1 parent 70cf1b3 commit af4cc38

File tree

6 files changed

+185
-6
lines changed

6 files changed

+185
-6
lines changed

‎linter/spectral.yml‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,7 @@ rules:
119119

120120
#/core/path-segments-kebab-case
121121
nlgov:paths-kebab-case:
122-
severity: warn
122+
severity: error
123123
message: "{{property}} is not kebab-case."
124124
given: $.paths[?(@property && [email protected](/\/openapi\.json/))]~
125125
then:
@@ -133,6 +133,19 @@ rules:
133133
# - Een pad mag eindigen met een `/`. Dat is volgens een andere regel niet toegestaan, maar we willen niet twee errors genereren
134134
match: ^(\/|(\/_[a-z0-9]+|\/(([a-z0-9\-]+|{[^}]+})(\/([a-z0-9\-\.]+|{[^}]+}))*)(\/_[a-z]+)?)\/?)$
135135

136+
#/core/query-keys-camel-case
137+
nlgov:query-keys-camel-case:
138+
severity: error
139+
message: "{{value}} is not lower camelCase."
140+
given:
141+
- $.paths.*.*.parameters[?(@.in=='query')]
142+
- $.components.securitySchemes[?(@.in=='query')]
143+
then:
144+
function: pattern
145+
field: name
146+
functionOptions:
147+
match: ^\$?[a-z][a-z0-9]*([A-Z][\w0-9]*)*$
148+
136149
nlgov:schema-camel-case:
137150
severity: warn
138151
message: "Schema name should be UpperCamelCase in {{path}}"

‎linter/testcases/cor-api/expected-output.txt‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
/testcases/cor-api/openapi.json
33
70:35 warning nlgov:use-problem-schema The content type of an error response should be application/problem+json or application/problem+xml to match RFC 9457. paths./heartbeat.get.responses[429].content
44
80:35 warning nlgov:use-problem-schema The content type of an error response should be application/problem+json or application/problem+xml to match RFC 9457. paths./heartbeat.get.responses[503].content
5-
181:29 warning nlgov:paths-kebab-case /laatsteWijziging is not kebab-case. paths./laatsteWijziging
5+
181:29 error nlgov:paths-kebab-case /laatsteWijziging is not kebab-case. paths./laatsteWijziging
66
211:35 warning nlgov:use-problem-schema The content type of an error response should be application/problem+json or application/problem+xml to match RFC 9457. paths./laatsteWijziging.get.responses[400].content
77
221:35 warning nlgov:use-problem-schema The content type of an error response should be application/problem+json or application/problem+xml to match RFC 9457. paths./laatsteWijziging.get.responses[404].content
88
231:35 warning nlgov:use-problem-schema The content type of an error response should be application/problem+json or application/problem+xml to match RFC 9457. paths./laatsteWijziging.get.responses[405].content
@@ -25,4 +25,4 @@
2525
734:35 warning nlgov:use-problem-schema The content type of an error response should be application/problem+json or application/problem+xml to match RFC 9457. paths./organisaties/{oin}.get.responses[500].content
2626
744:35 warning nlgov:use-problem-schema The content type of an error response should be application/problem+json or application/problem+xml to match RFC 9457. paths./organisaties/{oin}.get.responses[503].content
2727

28-
✖ 24 problems (0 errors, 24 warnings, 0 infos, 0 hints)
28+
✖ 24 problems (1 error, 23 warnings, 0 infos, 0 hints)

‎linter/testcases/paths-kebab-incorrect/expected-output.txt‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11

22
/testcases/paths-kebab-incorrect/openapi.json
3-
67:25 warning nlgov:paths-kebab-case /camelCasePad is not kebab-case. paths./camelCasePad
3+
67:25 error nlgov:paths-kebab-case /camelCasePad is not kebab-case. paths./camelCasePad
44

5-
✖ 1 problem (0 errors, 1 warning, 0 infos, 0 hints)
5+
✖ 1 problem (1 error, 0 warnings, 0 infos, 0 hints)

‎linter/testcases/query-keys-camel-case/expected-output.txt‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
2+
/testcases/query-keys-camel-case/openapi.json
3+
84:33 error nlgov:query-keys-camel-case kebab-case is not lower camelCase. paths./resource.get.parameters[1].name
4+
91:33 error nlgov:query-keys-camel-case _startMetSlash is not lower camelCase. paths./resource.get.parameters[2].name
5+
98:33 error nlgov:query-keys-camel-case 9startMetGetal is not lower camelCase. paths./resource.get.parameters[3].name
6+
105:33 error nlgov:query-keys-camel-case snake_case is not lower camelCase. paths./resource.get.parameters[4].name
7+
112:33 error nlgov:query-keys-camel-case UpperCamelCase is not lower camelCase. paths./resource.get.parameters[5].name
8+
9+
✖ 5 problems (5 errors, 0 warnings, 0 infos, 0 hints)

‎linter/testcases/query-keys-camel-case/openapi.json‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
{
2+
"openapi": "3.0.3",
3+
"info": {
4+
"title": "Baseline",
5+
"description": "Deze OpenAPI specification bevat het minimale om aan alle regels te voldoen.",
6+
"contact": {
7+
"name": "Beheerder",
8+
"url": "https://www.example.com",
9+
"email": "[email protected]"
10+
},
11+
"version": "1.0.0"
12+
},
13+
"servers": [
14+
{
15+
"url": "https://example.com/api/v1"
16+
}
17+
],
18+
"security": [
19+
{
20+
"default": []
21+
}
22+
],
23+
"tags": [
24+
{
25+
"name": "openapi"
26+
},
27+
{
28+
"name": "resource"
29+
}
30+
],
31+
"paths": {
32+
"/openapi.json": {
33+
"get": {
34+
"tags": [
35+
"openapi"
36+
],
37+
"description": "OpenAPI document",
38+
"operationId": "getOpenapiJSON",
39+
"parameters": [],
40+
"responses": {
41+
"200": {
42+
"description": "OK",
43+
"headers": {
44+
"API-Version": {
45+
"description": "De huidige versie van de applicatie",
46+
"style": "simple",
47+
"schema": {
48+
"type": "string"
49+
}
50+
},
51+
"access-control-allow-origin": {
52+
"description": "Alle origins mogen bij deze resource",
53+
"schema": {
54+
"type": "string"
55+
}
56+
}
57+
}
58+
}
59+
},
60+
"security": [
61+
{
62+
"default": []
63+
}
64+
]
65+
}
66+
},
67+
"/resource": {
68+
"get": {
69+
"tags": [
70+
"resource"
71+
],
72+
"description": "resource",
73+
"operationId": "getResource",
74+
"parameters": [
75+
{
76+
"in": "query",
77+
"name": "lowerCamelCase",
78+
"schema": {
79+
"type": "string"
80+
}
81+
},
82+
{
83+
"in": "query",
84+
"name": "kebab-case",
85+
"schema": {
86+
"type": "string"
87+
}
88+
},
89+
{
90+
"in": "query",
91+
"name": "_startMetSlash",
92+
"schema": {
93+
"type": "string"
94+
}
95+
},
96+
{
97+
"in": "query",
98+
"name": "9startMetGetal",
99+
"schema": {
100+
"type": "string"
101+
}
102+
},
103+
{
104+
"in": "query",
105+
"name": "snake_case",
106+
"schema": {
107+
"type": "string"
108+
}
109+
},
110+
{
111+
"in": "query",
112+
"name": "UpperCamelCase",
113+
"schema": {
114+
"type": "string"
115+
}
116+
}
117+
],
118+
"responses": {
119+
"200": {
120+
"description": "OK",
121+
"headers": {
122+
"API-Version": {
123+
"description": "De huidige versie van de applicatie",
124+
"style": "simple",
125+
"schema": {
126+
"type": "string"
127+
}
128+
}
129+
}
130+
}
131+
},
132+
"security": [
133+
{
134+
"default": []
135+
}
136+
]
137+
}
138+
}
139+
},
140+
"components": {
141+
"schemas": {
142+
},
143+
"securitySchemes": {
144+
"default": {
145+
"type": "oauth2",
146+
"flows": {
147+
"implicit": {
148+
"authorizationUrl": "https://test.com",
149+
"scopes": {}
150+
}
151+
}
152+
}
153+
}
154+
}
155+
}

‎sections/designRules.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -168,7 +168,7 @@ A resource that corresponds to a single conceptual entity is referred to as a [=
168168
<dt>Statement</dt>
169169
<dd>
170170
<div>
171-
<p>Query keys in a [=URI=] MUST only contain letters and digits, where the first letter of each word is capitalized, except for the first letter of the entire compound word. This is also known as <a href="https://developer.mozilla.org/en-US/docs/Glossary/Camel_case">lower camelCase</a>. This also implies that diacritics MUST be normalized and special characters MUST be omitted.
171+
<p>Query keys in a [=URI=] MUST only contain letters and digits, where the first letter of each word is capitalized, except for the first letter (MUST NOT be a digit) of the entire compound word. This is also known as <a href="https://developer.mozilla.org/en-US/docs/Glossary/Camel_case">lower camelCase</a>. This also implies that diacritics MUST be normalized and special characters MUST be omitted.
172172
</div>
173173
</dd>
174174
<dt>Rationale</dt>
@@ -179,6 +179,8 @@ A resource that corresponds to a single conceptual entity is referred to as a [=
179179
<pre class="nohighlight example-correct">https://api.example.org/v1/gebouwen?typeGebouw=woning</pre>
180180
<p>URI query key not using camelCase (incorrect):</p>
181181
<pre class="nohighlight example-incorrect">https://api.example.org/v1/gebouwen?type-gebouw=woning</pre>
182+
<p>URI query key starts with digit (incorrect):</p>
183+
<pre class="nohighlight example-incorrect">https://api.example.org/v1/gebouwen?2ndReviewer=alice</pre>
182184
</div>
183185
</dd>
184186
<dt>How to test</dt>

0 commit comments

Comments
 (0)