Setup linting for your OpenAPI Spec

To ensure that your SDKs are free of bugs & ergonomic (i.e. meaningful namespaces, succinct method name, and legible class names), Konfig has created a comprehensive set of rules that your OAS must pass. All lint rules and their explanations are documented here.

Methods

There are four ways to lint your spec:

1. GitHub Action
2. VSCode Extension
3. CLI
4. REST API

Required Setup

Ensure you have the konfig-cli installed by running

_10

npm install -g konfig-cli

GitHub Action Setup

To setup GitHub Action copy the following template to .github/workflows/konfig-lint.yaml and configure the following values:

1. Target branch
2. Path to OAS

.github/workflows/konfig-lint.yaml

_25

name: "konfig-lint-openapi-spec"

_25

on:

_25

pull_request:

_25

push:

_25

branches:

_25

- main

_25

jobs:

_25

konfig-lint-openapi-spec:

_25

runs-on: ubuntu-latest

_25

env:

_25

CLI_VERSION: 1.0.181

_25

steps:

_25

- uses: actions/checkout@v3

_25

- name: Cache node_modules

_25

id: cache-npm

_25

uses: actions/cache@v3

_25

with:

_25

path: ~/.npm

_25

key: ${{ runner.os }}-build-${{ env.CLI_VERSION }}

_25

- name: Install Konfig CLI

_25

run: npm install -g konfig-cli@$CLI_VERSION

_25

- name: Initialize Linting Rules

_25

run: konfig init -s

_25

- name: Lint OpenAPI Spec

_25

run: konfig lint path/to/openapi.yaml

Commit and push the generated file:

_19

~/Git/my-repo

_19

❯ git status

_19

On branch master

_19

Your branch is up to date with 'origin/master'.

_19

_19

Untracked files:

_19

(use "git add <file>..." to include in what will be committed)

_19

.github/

_19

_19

nothing added to commit but untracked files present (use "git add" to track)

_19

_19

~/Git/my-repo

_19

❯ git add -A

_19

_19

~/Git/my-repo

_19

❯ git commit -m "Commit Konfig lint GitHub action"

_19

[master 83d1f7e] Commit Konfig lint GitHub action

_19

1 file changed, 26 insertions(+)

_19

create mode 100644 .github/workflows/konfig-lint.yaml

On every PR or commit to your target branch the lint workflow will fail if any warnings or errors occur when linting your OAS.

VSCode Extension or CLI Setup

Initialize your target repository (the one that has your OpenAPI spec) with:

_10

❯ konfig init -s

_10

Downloading Konfig's lint rules... done

_10

Setting up Spectral... done

Commit the generated files

_25

~/Git/my-repo

_25

❯ git status

_25

On branch master

_25

Your branch is ahead of 'origin/master' by 1 commit.

_25

(use "git push" to publish your local commits)

_25

_25

Untracked files:

_25

(use "git add <file>..." to include in what will be committed)

_25

.konfig/

_25

.spectral.yaml

_25

.vscode/

_25

_25

nothing added to commit but untracked files present (use "git add" to track)

_25

_25

~/Git/my-repo

_25

❯ git add -A

_25

_25

~/Git/my-repo

_25

❯ git commit -m "Commit Konfig linting ruleset and VSCode settings"

_25

[master 06c577e] Commit Konfig linting ruleset and VSCode settings

_25

4 files changed, 28 insertions(+)

_25

create mode 100644 .konfig/ruleset.js

_25

create mode 100644 .spectral.yaml

_25

create mode 100644 .vscode/extensions.json

_25

create mode 100644 .vscode/settings.json

info

To update your ruleset to the latest verson simply run

_10

konfig init -s

And commit the updated ruleset.

Linting with VSCode Extension

When opening VSCode to your repo, you will be prompted to install the Spectral extension.

Click Install to install the Spectral extension. When viewing any OAS, you will see inline errors.

To see all the errors, open the "PROBLEMS" tab at the bottom of VSCode.

Make sure that showing all problems is enabled

Linting with CLI

To lint with CLI run konfig lint inside the directory that contains your konfig.yaml file.

_10

❯ konfig lint

_10

_10

/api.yaml

_10

22:10 warning operation-operationId Operation must have "operationId" for generated SDK method names. paths./pet.post

_10

_10

✖ 1 problem (0 errors, 1 warning, 0 infos, 0 hints)

REST API

For access to the REST API please setup a time to talk and we will get you setup.