Skip to content

Latest commit

 

History

History
76 lines (42 loc) · 4.1 KB

API-linting-Implementation-Guideline.md

File metadata and controls

76 lines (42 loc) · 4.1 KB
Raw

CAMARA OpenAPI Linting Rules Implementation Guideline [ How to integrate the rules into CAMARA repository ]

Introduction

This guide provides instructions on how to implement linting rules for the CAMARA APIs using two methods:

Both methods use the Spectral tool. All needed files are stored in the artifacts subfolder. The target method is linting rules integration with CAMARA API subproject repositories using GitHub Actions.

Spectral Configuration

The Spectral configuration consists of .spectral.yml file, which contains all the rules defined for CAMARA OpenAPI specification as described in Linting-rules.md

This file consolidates all rules:

  1. Spectral Core OpenAPI specification linting ruleset:

    Ruleset extension: extends: "spectral:oas"

  2. Spectral rules with built-in functions

  3. Spectral rules with custom JavaScript functions

GitHub Actions Integration

  1. Add .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 that are imported in .spectral.yml (some rules require custom JavaScript functions to execute).

  3. Add spectral_oas_lint.yml to GitHub action workflows in .github/workflows folder which includes the configuration of Spectral workflow for GitHub actions.

  4. Add megalinter.yml to GitHub action workflows in .github/workflows folder which includes the configuration of Megalinter and Spectral for GitHub actions.

Manually running linting workflow

spectral_oas_lint.yml includes configuration of the OAS linting workflow to be run manually as described in GitHub Actions documentation.

The rules will be applied to all files with *.yaml extension in '/code/API_definitions/' folder of the repository. 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 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 megalinter.yml 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.

API Linting configuration steps for local deployment

  1. Install Spectral locally:

    npm install -g @stoplight/spectral

  2. Install Spectral functions locally:

    npm install --save @stoplight/spectral-functions

  3. Save files locally:

    Save ".spectral.yml" file (contains Linting rules) and lint_function folder (contains JavaScript customized functions) at the root location.

  4. Apply spectral rules on API specification locally:

    spectral lint openapi.yaml --verbose --ruleset .spectral.yml

    Replace 'openapi.yaml' with the path to your OpenAPI specification file.