- Open in github.dev
- Open in a new github.dev tab
- Open in codespace
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-/
.spectral.yml
t
261 lines (242 loc) · 9.83 KB
/
.spectral.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
# CAMARA Project - linting ruleset - documentation avaialable here:
# https://github.com/camaraproject/Commonalities/blob/main/documentation/Linting-rules.md
# Changelog:
# - 31.01.2024: Initial version
# - 19.03.2024: Corrected camara-http-methods rule
-
-
extends: "spectral:oas"
functions:
- camara-reserved-words
- camara-language-avoid-telco
- camara-security-no-secrets-in-path-or-query-parameters
functionsDir: "./lint_function"
rules:
# Built-in OpenAPI Specification ruleset. Each rule then can be enabled individually.
# The severity keyword is optional in rule definition and can be error, warn, info, hint, or off. The default value is warn.
contact-properties: false
duplicated-entry-in-enum: true
info-contact: true
info-description: true
info-license: true
license-url: true
no-$ref-siblings: error
no-eval-in-markdown: true
no-script-tags-in-markdown: true
openapi-tags: false
openapi-tags-alphabetical: false
openapi-tags-uniqueness: error
operation-description: true
operation-operationId: true
operation-operationId-unique: error
operation-operationId-valid-in-url: true
operation-parameters: true
operation-singular-tag: true
operation-success-response: true
operation-tags: true
operation-tag-defined: true
path-declarations-must-exist: true
path-keys-no-trailing-slash: true
path-not-include-query: true
path-params: error
tag-description: false
typed-enum: true
oas3-api-servers: true
oas3-examples-value-or-externalValue: true
oas3-operation-security-defined: false
oas3-parameter-description: false
oas3-schema: true
oas3-server-not-example.com: false
oas3-server-trailing-slash: true
oas3-unused-component: true
oas3-valid-media-example: true
oas3-valid-schema-example: true
# oas3-server-variables: true
-
# Custom Rules Utilizing Spectral's Built-in Functions and JavaScript Implementations
-
camara-language-avoid-telco:
message: "{{error}}"
severity: hint
description: |
This rule checks for telco-specific terminology in your API definitions and suggests more inclusive terms.
given: "$..*.*"
then:
function: camara-language-avoid-telco
recommended: false # Set to true/false to enable/disable this rule
-
camara-oas-version:
message: "OpenAPI Version Error: The OpenAPI specification must adhere to version 3.0.3."
severity: error
description: |
This rule validates the OpenAPI version in your specification and requires compliance with version 3.0.3.
given: "$"
then:
field: openapi
function: pattern
functionOptions:
match: 3.0.3
recommended: true # Set to true/false to enable/disable this rule
-
camara-path-param-id:
message: "Path Parameter Naming Warning: Use 'resource_id' instead of just 'id' in path parameters."
severity: warn
description: |
This rule ensures consistent and descriptive naming for path parameters in your OpenAPI specification.
Please use 'resource_id' instead of just 'id' for your path parameters.
given: "$..parameters[?(@.in == 'path')]"
then:
field: name
function: pattern
functionOptions:
notMatch: \b(id|Id|ID|iD)\b
recommended: true # Set to true/false to enable/disable this rule
-
camara-security-no-secrets-in-path-or-query-parameters:
message: "Sensitive data found in path: {{error}} Consider avoiding the use of Sesentive data "
severity: warn
description: |
This rule checks for sensitive data ('MSISDN' and 'IMSI') in API paths and suggests avoiding their use.
given:
- "$.paths"
then:
function: camara-security-no-secrets-in-path-or-query-parameters
recommended: true # Set to true/false to enable/disable this rule
-
camara-http-methods:
description: "Ensure that all path URLs have valid HTTP methods (GET, PUT, POST, DELETE, PATCH, OPTIONS)."
message: "Invalid HTTP method for '{{path}}'. Must be one of get, put, post, delete, patch, options."
severity: error
given: $.paths[*][*]~
then:
function: pattern
functionOptions:
match: "^(get|put|post|delete|patch|options|parameters)$"
recommended: true # Set to true/false to enable/disable this rule
-
camara-get-no-request-body:
message: There must be no request body for Get and DELETE
severity: error
given:
- "$.paths.*.get"
- "$.paths.*.delete"
then:
field: requestBody
function: falsy
recommended: true # Set to true/false to enable/disable this rule
-
camara-reserved-words:
message: "Reserved words found {{error}} Consider avoiding the use of reserved word "
severity: warn
description: |
This rule checks Reserved words must not be used in the following parts of an API specification [Paths, Request Body properties, Component, Operation Id, Security Schema]
given:
- "$.paths" # Paths
- "$..parameters[*]" # Path or Query Parameter Names:
- "$..components.schemas.*.properties.*" # Request and Response body parameter
- "$.paths.*." # Path and Operation Names:
- "$.components.securitySchemes" # Security Schemes:
- "$.components.*.*" # Component Names:
- "$.paths.*.*.operationId" # OperationIds:
then:
function: camara-reserved-words
recommended: true # Set to true/false to enable/disable this rule
-
camara-routes-description:
message: "Functionality method description Warning: Each method should have description."
severity: warn
description: |
This rule checks if each operation (POST, GET, DELETE, PUT, PATCH, OPTIONS) in your API specification has a description.
Ensure that you have added a 'summary' field for each operation in your OpenAPI specification.
given:
- "$.paths.*.post"
- "$.paths.*.get"
- "$.paths.*.delete"
- "$.paths.*.put"
- "$.paths.*.patch"
- "$.paths.*.options"
then:
field: description
function: truthy
recommended: true # Set to true/false to enable/disable this rule
camara-parameters-descriptions:
message: "Parameter description is missing or empty: {{error}}"
severity: warn
description: |
This Spectral rule ensures that each path parameter in the API specification has a descriptive and meaningful description.
given:
- "$.paths..parameters.*"
then:
field: description
function: truthy
recommended: true # Set to true/false to enable/disable this rule
camara-response-descriptions:
message: "Parameter description is missing or empty: {{error}}"
severity: warn
description: |
This Spectral rule ensures that each responese object in the API specification has a descriptive and meaningful description.
given:
- "$.paths..responses.*"
then:
field: description
function: truthy
recommended: true # Set to true/false to enable/disable this rule
-
camara-properties-descriptions:
message: "Property description is missing or empty: {{error}}"
severity: warn
description: |
This Spectral rule ensures that each propoerty within objects in the API specification has a descriptive and meaningful description.
given:
- "$.components.*.*"
- "$.components.*.*.properties.*"
then:
field: description
function: truthy
recommended: true # Set to true/false to enable/disable this rule
camara-operation-summary:
message: "Operation Summary Warning: Each operation should include a short summary for better understanding."
severity: warn
description: |
This rule checks if each operation (POST, GET, DELETE, PUT, PATCH, OPTIONS) in your API specification has a meaningful summary.
Ensure that you have added a 'summary' field for each operation in your OpenAPI specification.
given:
- "$.paths.*.post"
- "$.paths.*.get"
- "$.paths.*.delete"
- "$.paths.*.put"
- "$.paths.*.patch"
- "$.paths.*.options"
then:
field: summary
function: truthy
recommended: true # Set to true/false to enable/disable this rule
-
camara-discriminator-use:
description: |
Ensure that API definition YAML files with oneOf or anyOf sections include a discriminator object for serialization, deserialization, and validation.
severity: hint
given: "$..[?(@.oneOf || @.anyOf)]"
then:
field: discriminator
function: truthy
description: "Discriminator object is required when using oneOf or anyOf."
recommended: true # Set to true/false to enable/disable this rule
-
camara-operationid-casing-convention:
message: Operation Id must be in Camel case "{{error}}"
severity: hint
description: |
This rule checks Operation ids should follow a specific case convention: camel case.
given: "$.paths.*.*.operationId"
then:
function: casing
functionOptions:
type: camel
recommended: true # Set to true/false to enable/disable this rule
-
camara-schema-casing-convention:
description: This rule checks schema should follow a specific case convention pascal case.
message: "{{property}} should be pascal case (UppperCamelCase)"
severity: warn
given: $.components.schemas[*]~
then:
function: casing
functionOptions:
type: pascal
recommended: true # Set to true/false to enable/disable this rule
-
camara-parameter-casing-convention:
description: Paths should be kebab-case.
severity: error
message: "{{property}} is not kebab-case: {{error}}"
given: $.paths[*]~
then:
function: pattern
functionOptions:
match: "^\/([a-z0-9]+(-[a-z0-9]+)*)?(\/[a-z0-9]+(-[a-z0-9]+)*|\/{.+})*$" # doesn't allow /asasd{asdas}sadas pattern or not closed braces
recommended: true # Set to true/false to enable/disable this rule