gl-code-quality-openapi-validator

Intro

gl-code-quality-openapi-validator converts the JSON file output of IBM's OpenAPI Validator to a GitLab Code Quality report JSON file. This file can then be exposed from a GitLab CI/CD job as an artifact and used to display code quality changes directly on the merge request.

Contents

• Installation
• Options
• GitLab
• Local Development
• Testing
• Conventional Commits
• GitHub Actions

Installation

To install this project you will need to have Node.js (>=16.0.0) installed. gl-code-quality-openapi-validator has been tested on the current LTS versions, 16.0.X and 18.0.X.

To install gl-code-quality-openapi-validator using npm execute:

npm install -g gl-code-quality-openapi-validator

The -g option installs gl-code-quality-openapi-validator globally so that it can be run from anywhere in the file system.

To execute gl-code-quality-openapi-validator after installing globally run:

gl-code-quality-openapi-validator

gl-code-quality-openapi-validator is designed to work with the JSON file output of IBM's OpenAPI Validator. Instructions for installation and usage can be found here.

The following command runs lint-openapi against openapi-spec.yml and redirects the JSON output to openapi-validator-report.json. gl-code-quality-openapi-validator is then able to convert this file into a GitLab Code Quality report.

lint-openapi --json openapi-spec.yml >> openapi-validator-report.json
gl-code-quality-openapi-validator -s openapi-spec.yml 

Options

gl-code-quality-openapi-validator has a handful of options. These options can be used to override the defaults that have been provided. For example:

gl-code-quality-openapi-validator -s ./specification/openapi-specification.yml -i /reporting/openapi-validator-report.json -o ./code-quality/gl-code-quality-report.json

Command Line Options

The following command line options are available for configuration:

| Option | Default | Description | |--------------------------------------|---------------------------------|------------------------------------------------------| | -V, --version | 1.0.0 | Output the version number | | -s, --specification <specification> | ./openapi-specification.yml | Filepath for the OpenAPI specification | | -i, --input <input> | ./openapi-validator-report.json | Filepath for the OpenAPI Validator JSON report input | | -o, --output <output> | ./gl-code-quality-report.json | Filepath for the GitLab Code Quality report output | | -h, --help | | display help for command |

GitLab

gl-code-quality-openapi-validator is intended to be used as part of a GitLab CI/CD pipeline job. The following code snippet provides an example job declaration.

openapi-validation:
  stage: code-quality
  image: node:latest
  script:
    - npm install -g ibm-openapi-validator @ibm-cloud/openapi-ruleset gl-code-quality-openapi-validator
    - lint-openapi --json ./openapi-specification.yml >> openapi-validator-report.json
    - gl-code-quality-openapi-validator -s ./openapi-specification.yml
  artifacts:
    reports:
      codequality: gl-code-quality-report.json

Local Development

Prerequisites

To install, run and modify this project you will need to have:

• Node.js
• Git

Installation

To start, please fork and clone the repository to your local machine. You are able to run the service directly on the command line or with your IDE of choice.

Running

Command Line

To run the service from the command line first you need to install the dependencies, install the project locally, and then execute gl-code-quality-openapi-validator.

npm install
npm install --global
gl-code-quality-openapi-validator

Testing

All tests have been written using Jest. To run the tests execute:

npm test

Code coverage is also measured by Jest and set to a minimum of 95%. To run tests with coverage execute:

npm run test:coverage

Code coverage reports can be found in the /coverage/ directory.

Conventional Commits

This project uses the Conventional Commits specification for commit messages. The specification provides a simple rule set for creating commit messages, documenting features, fixes, and breaking changes in commit messages.

A pre-commit configuration file has been provided to automate commit linting. Ensure that pre-commit has been installed and execute...

pre-commit install

...to add a commit Git hook to your local machine.

An automated pipeline job has been configured to lint commit messages on a push.

GitHub Actions

CI/CD pipelines has been created using GitHub Actions to automated tasks such as linting, testing, and releasing.

Build Workflow

The build workflow handles integration tasks. This workflow consists of two jobs, Git and Node, that run in parallel. This workflow is triggered on a push to a branch.

Git

This job automates tasks relating to repository linting and enforcing best practices.

Node

This job automates Node.js specific tasks.

Release Workflow

The release workflow handles release tasks. This workflow consists of one job, npm. This workflow is triggered manually from the GitHub Actions UI.

npm

This job automates tasks relating to updating changelog, and publishing to npm.