Skip to content
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

Replace broken links with relative links in API-linting-Implementation-Guideline.md #274

Merged
merged 10 commits into from
Aug 21, 2024
29 changes: 12 additions & 17 deletions documentation/API-linting-Implementation-Guideline.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,15 @@

## Introduction

This guide provides instructions on how to implement linting rules for the CAMARA APIs using two methods: **[GitHub Actions](API-linting-Implementation-Guideline.md#github-actions-integration)** and **[local deployment](API-linting-Implementation-Guideline.md#github-actions-integration)**, both methods use [Spectral tool](https://docs.stoplight.io/docs/spectral/674b27b261c3c-overview).
All needed files are stored in [artifacts subfolder](https://github.com/camaraproject/Commonalities/tree/API-linting-Implementation-Guideline/artifacts/linting_rules).

The target method is linting rules integration with CAMARA API subproject repositories using GitHub Actions.
This guide provides instructions on how to implement linting rules for the CAMARA APIs using two methods:
- [GitHub Actions](#github-actions-integration)
- [Local Deployment](#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](/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,21 +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/tree/API-linting-Implementation-Guideline/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 @@ -45,20 +44,16 @@ Write access to the repository is required to perform these steps.

The output from Spectral can be seen by expanding the step **Run Spectral Linting** of the given workflow run Actions section of GitHub repository.


### Megalinter integration

[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/lint_function/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/lint_function/workflows.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