Style Guides Rulebook Series: Automated API Design checks in CI

Public style guides are available for Professional and Enterprise workspaces. Simply log into your workspace, click on the Governance tab, and look for Public Style Guides, then enable the rules you want to use.

This is the third blog in our Style Guide Rulebook series. Check out the first and second ones for more insights.

Creating API style guides is very useful for bringing consistency across your API program. Much like code style checks, it’s a good idea to run Style guide checks within your CI against each pull request for an API design.

Irrespective of the CI pipeline or version control system that you’re using, you probably have existing status checks around code quality, testing, etc. Status checks let you know if your changes meet the conditions set for the project.

Spectral CLI

Spectral CLI can be used to add API design checks as a status check within your CI system. All you need is the spectral ruleset file and OpenAPI files that you need to lint against it within your repository.

You can lint multiple files at the same time against a custom ruleset:

spectral lint ./{path-to-api-design-files}/**/*.{json,yml,yaml} -r {path-to-spectral-file}

Other configuration options to note of:

-f, --format formatters to use for outputting results
# junit comes in very handy when uploading test results to CI systems
[choices: "json", "stylish", "junit", "html", "text", "teamcity", "pretty"] [default: "stylish"]

-o, --output where to output results

# if you want to fail on a severity below error, configure this
-F, --fail-severity results of this level or above will trigger a failure
[choices: "error", "warn", "info", "hint"] [default: "error"]

Read more about the CLI in detail here.

Setting up Spectral in your CI pipeline

In this guide, we’ll cover how to use spectral CLI within popular CI systems.

• GitHub
• CircleCI
• GitLab
• Bitbucket
• Azure DevOps

GitHub

GitHub has a powerful automation mechanism using GitHub actions which make it easy to automate software workflows. Spectral comes with a spectral action to lint your OpenAPI documents.

1. If you don’t have an existing GitHub workflow setup, add a new workflow from the Actions tab within your repository.

2. Add the following to your workflow file:

name: Run Spectral on Pull Requests

on:
  - pull_request

jobs:
  build:
    name: Run Spectral
    runs-on: ubuntu-latest
    steps:
      # Check out the repository
      - uses: actions/checkout@v2

      # Run Spectral
      - uses: stoplightio/spectral-action@latest
        with:
          file_glob: 'reference/*.yaml' # File pattern for your API design files
          spectral_ruleset: {path-to-ruleset}

Download this sample file: https://github.com/stoplightio/style-guides-rulebook-series/blob/master/.github/workflows/main.yml

3. Create a pull request within your repository and see the results for your API design checks.

4. Optional: You can also enforce that all errors must be fixed before a pull request can be merged by enabling the Require status checks to pass before merging option in the branch protection rules.

CircleCI

1. Create a CircleCI config file (.circleci/config.yml)to your repository if you don’t have one already.
2. Add the following to your config file:

# This config is equivalent to both the '.circleci/extended/orb-free.yml'
#and the base '.circleci/config.yml'
version: 2.1

# Orbs are reusable packages of CircleCI configuration that you may share across
# projects, enabling you to create encapsulated, parameterized commands, jobs,
# and executors that can be used across multiple projects.
# See: https://circleci.com/docs/2.0/orb-intro/
orbs:
  node: circleci/node@4.7

jobs:
  lint:
    docker:
      - image: cimg/node:16.10
    steps:
      # Checkout the code as the first step.
      - checkout
      # Create a folder for results to live in
      - run: "[ -d lint-results ] || mkdir lint-results"
      - run:
          name: Run Spectral Lint
          command: npx @stoplight/spectral-cli lint ./reference/**/*.{json,yml,yaml} -r .spectral.json 
            -o test-results/spectral-results.xml
            -f junit
      - store_test_results:
          path: test-results

workflows:
  spectral-lint:
    jobs:
      - lint

Or download this sample file: https://github.com/stoplightio/style-guides-rulebook-series/blob/master/.circleci/config.yml

3. Check out the results for your API design check within CircleCI

GitLab

1. Create a GitLab CI config file (.gitlab-ci.yml) for your repository if you don’t have one already.
2. Add the following to your config file:

image: node:latest

stages:          # List of stages for jobs, and their order of execution
  - lint

spectral-linting:   # This job also runs in the test stage.
  stage: lint    # It can run at the same time as the unit-test-job (in parallel).
  script:
    - echo "Linting API Designs."
    - npx @stoplight/spectral-cli lint ./reference/**/*.{json,yml,yaml} -r .spectral.json -o test-results/spectral-results.xml -f junit
  artifacts:
    when: always
    reports:
      junit:
        - test-results/spectral-results.xml

Or download this sample file: https://github.com/stoplightio/style-guides-rulebook-series/blob/master/.gitlab-ci.yml

3. Check out the results for your API design check within GitLab

Bitbucket

1. Create a Bitbucket pipelines config file (bitbucket-pipelines.yml) for your repository if you don’t have one already.
2. Add the following to your config file:

image: atlassian/default-image:3

pipelines:
  default:
    - parallel:
      - step:
          name: 'Lint'
          script:
            - npx @stoplight/spectral-cli lint ./reference/**/*.{json,yml,yaml} -r .spectral.json -o test-results/spectral-results.xml -f junit

Or download this sample file: https://github.com/stoplightio/style-guides-rulebook-series/blob/master/bitbucket-pipelines.yml

3. Check out the results for your API design check within Bitbucket

Azure DevOps

1. Create an Azure DevOps pipelines config file (azure-pipelines.yml)to your repository if you don’t have one already.
2. Add the following to your config file:

trigger:
- master

steps:
- script: |
    npx @stoplight/spectral-cli lint ./reference/**/*.{json,yml,yaml} -r .spectral.json -o test-results/spectral-results.xml -f junit
  displayName: 'spectral lint'
  continueOnError: true

- task: PublishTestResults@2
  inputs:
    testResultsFormat: 'JUnit'
    testResultsFiles: 'test-results/spectral-results.xml'
    failTaskOnFailedTests: true
    testRunTitle: 'Spectral Linting Results'

Or download this sample file: https://github.com/stoplightio/style-guides-rulebook-series/blob/master/azure-pipelines.yml

3. Check out the results for your API design check within Azure DevOps

Stay tuned for more additions to the Style Guide Rulebook series in the coming weeks, but in the meantime, check out our new Shared Style Guides feature or our open-source linting tool, Spectral for yourself.