Skip to content

Commit

Permalink
Merge pull request #274 from eric-murray/main
Browse files Browse the repository at this point in the history
Replace broken links with relative links in API-linting-Implementation-Guideline.md
  • Loading branch information
rartych authored Aug 21, 2024
2 parents eefe95c + 1abf65b commit 36a98ef
Showing 1 changed file with 12 additions and 17 deletions.
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

0 comments on commit 36a98ef

Please sign in to comment.