Skip to content

Commit 689b171

Browse files
nicolacdnllnicolacdnll
authored
Merge pull request #216 from camaraproject/Kevsy-patch-9
Linting workflow added
2 parents e37fed1 + 6f7a192 commit 689b171

6 files changed

+536
-0
lines changed

‎.github/workflows/megalinter.yml

+78
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
# MegaLinter GitHub Action configuration file
3+
# More info at https://megalinter.io
4+
# CAMARA Project - Github Action for Pull Reqests
5+
# 31.01.2024 - initial version
6+
7+
name: MegaLinter
8+
9+
on: # yamllint disable-line rule:truthy
10+
# Pull Requests to main
11+
pull_request:
12+
branches: [master, main]
13+
14+
env: # Comment env block if you do not want to apply fixes
15+
# Apply linter fixes configuration
16+
APPLY_FIXES: all # When active, APPLY_FIXES must also be defined as environment variable (in github/workflows/mega-linter.yml or other CI tool)
17+
APPLY_FIXES_EVENT: pull_request # Decide which event triggers application of fixes in a commit or a PR (pull_request, push, all)
18+
APPLY_FIXES_MODE: commit # If APPLY_FIXES is used, defines if the fixes are directly committed (commit) or posted in a PR (pull_request)
19+
20+
concurrency:
21+
group: ${{ github.ref }}-${{ github.workflow }}
22+
cancel-in-progress: true
23+
24+
jobs:
25+
build:
26+
name: MegaLinter
27+
runs-on: ubuntu-latest
28+
permissions:
29+
# Give the default GITHUB_TOKEN write permission to commit and push, comment issues & post new PR
30+
# Remove the ones you do not need
31+
contents: write
32+
issues: write
33+
pull-requests: write
34+
steps:
35+
# Git Checkout
36+
- name: Checkout Code
37+
uses: actions/checkout@v4
38+
with:
39+
token: ${{ secrets.GITHUB_TOKEN }}
40+
fetch-depth: 0 # If you use VALIDATE_ALL_CODEBASE = true, you can remove this line to improve performances
41+
- name: Install Spectral
42+
run: npm install -g @stoplight/spectral
43+
- name: Install Spectral functions
44+
run: npm install -g @stoplight/spectral-functions
45+
# - name: Run spectral:oas Spectral Linting
46+
# run: spectral lint code/API_definitions/*.yaml --verbose --ruleset .spectral.yml
47+
# Replace openapi.yaml file with your API specification file
48+
49+
# MegaLinter
50+
- name: MegaLinter
51+
id: ml
52+
# You can override MegaLinter flavor used to have faster performances
53+
# More info at https://megalinter.io/flavors/
54+
uses: oxsecurity/megalinter/flavors/[email protected]
55+
env:
56+
# All available variables are described in documentation
57+
# https://megalinter.io/configuration/
58+
PRINT_ALPACA: false
59+
# VALIDATE_ALL_CODEBASE: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }} # Validates all source when push on main, else just the git diff with main. Override with true if you always want to lint all sources
60+
VALIDATE_ALL_CODEBASE: true
61+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
62+
# ADD YOUR CUSTOM ENV VARIABLES HERE OR DEFINE THEM IN A FILE .mega-linter.yml AT THE ROOT OF YOUR REPOSITORY
63+
DISABLE: COPYPASTE,MARKDOWN
64+
DISABLE_LINTERS: SPELL_CSPELL,SPELL_LYCHEE,YAML_PRETTIER,REPOSITORY_GRYPE, REPOSITORY_SEMGREP,REPOSITORY_DEVSKIM,REPOSITORY_KICS,REPOSITORY_TRIVY,REPOSITORY_TRIVY_SBOM,REPOSITORY_TRUFFLEHOG,REPOSITORY_CHECKOV,REPOSITORY_GITLEAKS,YAML_V8R,JAVA_PMD,JAVA_CHECKSTYLE
65+
YAML_YAMLLINT_CONFIG_FILE: ".yamllint.yaml"
66+
OPENAPI_SPECTRAL_CONFIG_FILE: ".spectral.yml"
67+
YAML_YAMLLINT_FILTER_REGEX_INCLUDE: "(code/)"
68+
OPENAPI_SPECTRAL_FILTER_REGEX_INCLUDE: "(code/)"
69+
70+
# Upload MegaLinter artifacts
71+
- name: Archive production artifacts
72+
if: ${{ success() }} || ${{ failure() }}
73+
uses: actions/upload-artifact@v4
74+
with:
75+
name: MegaLinter reports
76+
path: |
77+
megalinter-reports
78+
mega-linter.log

‎.github/workflows/spectral_oas_lint.yml

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
# CAMARA Project - workflow configuration to manually run CAMARA OAS rules
3+
# see https://docs.github.com/en/actions/using-workflows/manually-running-a-workflow
4+
# 31.01.2024 - initial version
5+
6+
name: Spectral manual run
7+
8+
on: workflow_dispatch
9+
10+
concurrency:
11+
group: ${{ github.ref }}-${{ github.workflow }}
12+
cancel-in-progress: true
13+
14+
jobs:
15+
build:
16+
name: Spectral linting
17+
runs-on: ubuntu-latest
18+
permissions:
19+
# Give the default GITHUB_TOKEN write permission to commit and push, comment issues & post new PR
20+
# Remove the ones you do not need
21+
contents: write
22+
issues: write
23+
pull-requests: write
24+
steps:
25+
# Git Checkout
26+
- name: Checkout Code
27+
uses: actions/checkout@v4
28+
with:
29+
token: ${{ secrets.GITHUB_TOKEN }}
30+
fetch-depth: 0 # If you use VALIDATE_ALL_CODEBASE = true, you can remove this line to improve performances
31+
- name: Install Spectral
32+
run: npm install -g @stoplight/spectral
33+
- name: Install Spectral functions
34+
run: npm install -g @stoplight/spectral-functions
35+
- name: Run Spectral linting
36+
run: spectral lint code/API_definitions/*.yaml --verbose --ruleset .spectral.yml

‎.spectral.yml

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

0 commit comments

Comments
 (0)