Skip to content

Commit

Permalink
Update API-linting-Implementation-Guideline.md
Browse files Browse the repository at this point in the history
  • Loading branch information
eric-murray authored Aug 5, 2024
1 parent 9c34602 commit 1cd7d6c
Showing 1 changed file with 11 additions and 11 deletions.
22 changes: 11 additions & 11 deletions documentation/API-linting-Implementation-Guideline.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,14 @@
## Introduction

This guide provides instructions on how to implement linting rules for the CAMARA APIs using two methods:
- [GitHub Actions](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-linting-Implementation-Guideline.md#spectral-configuration)
- [Local Deployment](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-linting-Implementation-Guideline.md#api-linting-configuration-steps-for-local-deployment)
- [GitHub Actions](./API-linting-Implementation-Guideline.md#github-actions-integration)
- [Local Deployment](./API-linting-Implementation-Guideline.md#api-linting-configuration-steps-for-local-deployment)

Both methods use the [Spectral](https://docs.stoplight.io/docs/spectral/674b27b261c3c-overview) tool. All needed files are stored in the [artifacts subfolder](https://github.com/camaraproject/Commonalities/tree/main/artifacts/linting_rules). The target method is linting rules integration with CAMARA API subproject repositories using GitHub Actions.
Both methods use the [Spectral](https://docs.stoplight.io/docs/spectral/674b27b261c3c-overview) tool. All needed files are stored in the [artifacts subfolder](../artifacts/linting_rules). The target method is linting rules integration with CAMARA API subproject repositories using GitHub Actions.

## Spectral Configuration

The Spectral configuration consists of <b><a href="https://github.com/camaraproject/Commonalities/blob/main/artifacts/linting_rules/.spectral.yml"> .spectral.yml</a></b> file, which contains all the rules defined for CAMARA OpenAPI specification as described in [Linting-rules.md](Linting-rules.md)
The Spectral configuration consists of <b><a href="../artifacts/linting_rules/.spectral.yml"> .spectral.yml</a></b> file, which contains all the rules defined for CAMARA OpenAPI specification as described in [Linting-rules.md](Linting-rules.md)

This file consolidates all rules:

Expand All @@ -19,20 +19,20 @@ This file consolidates all rules:
`Ruleset extension: extends: "spectral:oas"`

2. Spectral rules with built-in functions
3. Spectral rules with custom<a href="https://github.com/camaraproject/Commonalities/blob/main/artifacts/linting_rules/lint_function"> JavaScript functions</a>
3. Spectral rules with custom<a href="../artifacts/linting_rules/lint_function"> JavaScript functions</a>

## GitHub Actions Integration

1. Add **[.spectral.yml](https://github.com/camaraproject/Commonalities/blob/main/artifacts/linting_rules/.spectral.yml)** (rules) file to -> root location of repository
1. Add **[.spectral.yml](../artifacts/linting_rules/.spectral.yml)** (rules) file to -> root location of repository

2. Create **lint-function** folder

Make a folder named `lint_function` at root location and add custom [JavaScript function files](https://github.com/camaraproject/Commonalities/blob/main/artifacts/linting_rules/lint_function) that are imported in .spectral.yml (some rules require custom JavaScript functions to execute).
Make a folder named `lint_function` at root location and add custom [JavaScript function files](../artifacts/linting_rules/lint_function) that are imported in .spectral.yml (some rules require custom JavaScript functions to execute).

3. Add **[spectral_oas_lint.yml](https://github.com/camaraproject/Commonalities/blob/main/artifacts/linting_rules/.github/workflows/spectral_oas_lint.yml)** to GitHub action workflows in `.github/workflows` folder
3. Add **[spectral_oas_lint.yml](../artifacts/linting_rules/.github/workflows/spectral_oas_lint.yml)** to GitHub action workflows in `.github/workflows` folder
which includes the configuration of Spectral workflow for GitHub actions.

4. Add <b>[megalinter.yml](https://github.com/camaraproject/Commonalities/blob/main/artifacts/linting_rules/.github/workflows/megalinter.yml)</b> to GitHub action workflows in `.github/workflows` folder
4. Add <b>[megalinter.yml](../artifacts/linting_rules/.github/workflows/megalinter.yml)</b> to GitHub action workflows in `.github/workflows` folder
which includes the configuration of Megalinter and Spectral for GitHub actions.

### Manually running linting workflow
Expand All @@ -49,11 +49,11 @@ The output from Spectral can be seen by expanding the step **Run Spectral Lintin
[Megalinter](https://megalinter.io/latest/) is an Open-Source tool for CI/CD workflows that analyzes the consistency of code, configurations, and scripts in repository sources. Megalinter supports Spectral linting.
The Megalinter job will be automatically activated once you submit a pull request on the [main/master] branch of the CAMARA repository, as configured in megalinter.yml.

The Megalinter configuration consists of the <b><a href="https://github.com/camaraproject/Commonalities/blob/main/artifacts/linting_rules/.github/workflows/megalinter.yml">megalinter.yml </a></b> file containing the necessary settings to run Megalinter and Spectral jobs on GitHub actions.
The Megalinter configuration consists of the <b><a href="../artifacts/linting_rules/.github/workflows/megalinter.yml">megalinter.yml </a></b> file containing the necessary settings to run Megalinter and Spectral jobs on GitHub actions.

Additionally, Megalinter also supports linting of YAML files. To enable this, users need to add the following ruleset files to the root location.

- <b>YAML Linting:</b> <a href="https://github.com/camaraproject/Commonalities/blob/main/artifacts/linting_rules/.yamllint.yaml"> .yamllint.yaml </a>
- <b>YAML Linting:</b> <a href="../artifacts/linting_rules/.yamllint.yaml"> .yamllint.yaml </a>

## API Linting configuration steps for local deployment

Expand Down

0 comments on commit 1cd7d6c

Please sign in to comment.