generated from camaraproject/Template_API_Repository
-
Notifications
You must be signed in to change notification settings - Fork 28
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
API linting implementation guideline (#1) #110
Merged
rartych
merged 15 commits into
camaraproject:main
from
ravindrapalaskar17:API-linting-Implementation-Guideline
Feb 9, 2024
Merged
Changes from all commits
Commits
Show all changes
15 commits
Select commit
Hold shift + click to select a range
ee82212
Draft/api linting implementation guideline (#1)
ravindrapalaskar17 e8c103a
Update Sensitive data spelling and add phoneNumber in array.
ravindrapalaskar17 c42c43b
Update Sensitive spelling from function
ravindrapalaskar17 64e1624
Update API guideline document
ravindrapalaskar17 f5d771c
Replace type pattern with spectral core casing function [ kebab and p…
ravindrapalaskar17 9842099
change megalinter.yml position
ravindrapalaskar17 ad14389
change position of megalinter.yml file
ravindrapalaskar17 c7481b0
change position of javalint.xml
ravindrapalaskar17 91bf9b3
change location of .yamllint.yaml
ravindrapalaskar17 da45a2e
Delete artifacts/linting_rules/lint_function/workflows directory
ravindrapalaskar17 aaeb455
Delete artifacts/Github_templates/.github/workflows directory
ravindrapalaskar17 29e4e9d
Api linting rartych (#2)
rartych 3f3ff60
Update indentation in .spectral.yml file
ravindrapalaskar17 38b97bc
Update megalinter.yml
rartych e30f39a
Update .yamllint.yaml
rartych File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,78 @@ | ||
--- | ||
# MegaLinter GitHub Action configuration file | ||
# More info at https://megalinter.io | ||
# CAMARA Project - Github Action for Pull Reqests | ||
# 31.01.2024 - initial version | ||
|
||
name: MegaLinter | ||
|
||
on: # yamllint disable-line rule:truthy | ||
# Pull Requests to main | ||
pull_request: | ||
branches: [master, main] | ||
|
||
env: # Comment env block if you do not want to apply fixes | ||
# Apply linter fixes configuration | ||
APPLY_FIXES: all # When active, APPLY_FIXES must also be defined as environment variable (in github/workflows/mega-linter.yml or other CI tool) | ||
APPLY_FIXES_EVENT: pull_request # Decide which event triggers application of fixes in a commit or a PR (pull_request, push, all) | ||
APPLY_FIXES_MODE: commit # If APPLY_FIXES is used, defines if the fixes are directly committed (commit) or posted in a PR (pull_request) | ||
|
||
concurrency: | ||
group: ${{ github.ref }}-${{ github.workflow }} | ||
cancel-in-progress: true | ||
|
||
jobs: | ||
build: | ||
name: MegaLinter | ||
runs-on: ubuntu-latest | ||
permissions: | ||
# Give the default GITHUB_TOKEN write permission to commit and push, comment issues & post new PR | ||
# Remove the ones you do not need | ||
contents: write | ||
issues: write | ||
pull-requests: write | ||
steps: | ||
# Git Checkout | ||
- name: Checkout Code | ||
uses: actions/checkout@v4 | ||
with: | ||
token: ${{ secrets.GITHUB_TOKEN }} | ||
fetch-depth: 0 # If you use VALIDATE_ALL_CODEBASE = true, you can remove this line to improve performances | ||
- name: Install Spectral | ||
run: npm install -g @stoplight/spectral | ||
- name: Install Spectral functions | ||
run: npm install -g @stoplight/spectral-functions | ||
# - name: Run spectral:oas Spectral Linting | ||
# run: spectral lint code/API_definitions/*.yaml --verbose --ruleset .spectral.yml | ||
# Replace openapi.yaml file with your API specification file | ||
|
||
# MegaLinter | ||
- name: MegaLinter | ||
id: ml | ||
# You can override MegaLinter flavor used to have faster performances | ||
# More info at https://megalinter.io/flavors/ | ||
uses: oxsecurity/megalinter/flavors/java@v7.3.0 | ||
env: | ||
# All available variables are described in documentation | ||
# https://megalinter.io/configuration/ | ||
PRINT_ALPACA: false | ||
# 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 | ||
VALIDATE_ALL_CODEBASE: true | ||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | ||
# ADD YOUR CUSTOM ENV VARIABLES HERE OR DEFINE THEM IN A FILE .mega-linter.yml AT THE ROOT OF YOUR REPOSITORY | ||
DISABLE: COPYPASTE,MARKDOWN | ||
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 | ||
YAML_YAMLLINT_CONFIG_FILE: ".yamllint.yaml" | ||
OPENAPI_SPECTRAL_CONFIG_FILE: ".spectral.yml" | ||
YAML_YAMLLINT_FILTER_REGEX_INCLUDE: "(code/)" | ||
OPENAPI_SPECTRAL_FILTER_REGEX_INCLUDE: "(code/)" | ||
|
||
# Upload MegaLinter artifacts | ||
- name: Archive production artifacts | ||
if: ${{ success() }} || ${{ failure() }} | ||
uses: actions/upload-artifact@v4 | ||
with: | ||
name: MegaLinter reports | ||
path: | | ||
megalinter-reports | ||
mega-linter.log |
36 changes: 36 additions & 0 deletions
36
artifacts/linting_rules/.github/workflows/spectral_oas_lint.yml
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,36 @@ | ||
--- | ||
# CAMARA Project - workflow configuration to manually run CAMARA OAS rules | ||
# see https://docs.github.com/en/actions/using-workflows/manually-running-a-workflow | ||
# 31.01.2024 - initial version | ||
|
||
name: Spectral manual run | ||
|
||
on: workflow_dispatch | ||
|
||
concurrency: | ||
group: ${{ github.ref }}-${{ github.workflow }} | ||
cancel-in-progress: true | ||
|
||
jobs: | ||
build: | ||
name: Spectral linting | ||
runs-on: ubuntu-latest | ||
permissions: | ||
# Give the default GITHUB_TOKEN write permission to commit and push, comment issues & post new PR | ||
# Remove the ones you do not need | ||
contents: write | ||
issues: write | ||
pull-requests: write | ||
steps: | ||
# Git Checkout | ||
- name: Checkout Code | ||
uses: actions/checkout@v4 | ||
with: | ||
token: ${{ secrets.GITHUB_TOKEN }} | ||
fetch-depth: 0 # If you use VALIDATE_ALL_CODEBASE = true, you can remove this line to improve performances | ||
- name: Install Spectral | ||
run: npm install -g @stoplight/spectral | ||
- name: Install Spectral functions | ||
run: npm install -g @stoplight/spectral-functions | ||
- name: Run Spectral linting | ||
run: spectral lint code/API_definitions/*.yaml --verbose --ruleset .spectral.yml |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,258 @@ | ||
# CAMARA Project - linting ruleset - documentation avaialable here: | ||
# https://github.com/camaraproject/Commonalities/blob/main/documentation/Linting-rules.md | ||
# 31.01.2024 - initial version | ||
|
||
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)$" | ||
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: | ||
rartych marked this conversation as resolved.
Show resolved
Hide resolved
|
||
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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Why not using built-in type: kebab There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Tested and updated PR with spectral core function kebab |
||
recommended: true # Set to true/false to enable/disable this rule |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Not all usages of oneOf/anyOf are related to polymorphism, e.g. https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_definitions/qod-api.yaml#L963