Backstage API Spectral Linter Plugin

API Spectral Linter brings Spectral code checks into your Backstage API catalog. Spectral is a linter for YAML and JSON that validates OpenAPI and AsyncAPI using rulesets. The plugin runs those checks on each API entity in Backstage. You see findings inside the portal with clear titles and descriptions. When available it includes links to external rule docs. The results are easy to scan so you can fix issues fast.

Use it to keep an API style guide consistent across teams. Catch missing fields or broken examples early in the review flow. Standardize names and structure across services. Reduce drift as your system grows. The plugin works with rulesets you host. You can set defaults for OpenAPI or AsyncAPI. You can override per API through an entity annotation when you need to.

The view also formats API definitions for readability. Rule descriptions render as markdown for better context. Updates track new Backstage releases often so the plugin stays current with the platform. If you already rely on API Docs in Backstage, this adds quality control in the same place your engineers work. It helps raise the bar on API docs and design without leaving the developer portal.

Uploaded from https://raw.githubusercontent.com/dweber019/backstage-plugins/main/plugins/api-docs-spectral-linter/docs/spectral-linter.png

Installation Instructions

These instructions apply to self-hosted Backstage only.

Install the package

From the Backstage root run

Copy

yarn --cwd packages/app add @dweber019/backstage-plugin-api-docs-spectral-linter

Add the linter tab to API entity pages

Open packages app src components catalog EntityPage.tsx
Add the imports

Copy

import {
  EntityApiDocsSpectralLinterContent,
  isApiDocsSpectralLinterAvailable,
} from '@dweber019/backstage-plugin-api-docs-spectral-linter';

Add a new route inside your API entity layout

If your file defines an apiPage layout, add a new tab like this

Copy

// inside your <EntityLayout> for API entities
<EntityLayout.Route
  if={isApiDocsSpectralLinterAvailable}
  path="/linter"
  title="Linter"
>
  <EntityApiDocsSpectralLinterContent />
</EntityLayout.Route>

A common pattern looks like this

Copy

// packages/app/src/components/catalog/EntityPage.tsx
import React from 'react';
import { EntityLayout } from '@backstage/plugin-catalog';
import {
  EntityApiDocsSpectralLinterContent,
  isApiDocsSpectralLinterAvailable,
} from '@dweber019/backstage-plugin-api-docs-spectral-linter';

const apiPage = (
  <EntityLayout>
    {/* other tabs */}
    <EntityLayout.Route
      if={isApiDocsSpectralLinterAvailable}
      path="/linter"
      title="Linter"
    >
      <EntityApiDocsSpectralLinterContent />
    </EntityLayout.Route>
  </EntityLayout>
);

export const entityPage = apiPage;

Configure rule sets on API entities

The plugin checks for an annotation on the API entity. Add it to your API entity YAML. Use a url that returns yaml or json

Copy

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: my-service-api
  annotations:
    backstage.io/spectral-ruleset-url: https://example.com/rulesets/openapi-rules.yaml
spec:
  type: openapi
  lifecycle: production
  owner: team-a
  definition:
    $text: https://example.com/apis/my-service-openapi.yaml

Optional default rule sets

You can set default rule sets in app-config.yaml. The plugin will use these when the entity does not set its own annotation. Both OpenAPI and AsyncAPI are supported

Copy

spectralLinter:
  openApiRulesetUrl: https://example.com/rulesets/openapi-rules.yaml
  asyncApiRulesetUrl: https://example.com/rulesets/asyncapi-rules.yaml

Backend install

This plugin has only a frontend part. No backend package is needed

Changelog

This changelog is produced from commits made to the API Spectral Linter plugin since 7 months ago. It may not contain information about all commits. Releases and version bumps are intentionally omitted. This changelog is generated by AI.

v0.5.1

Bug fixes

Update Spectral core to 1.20.0. Fix rule object handling in #107. Merged 1 month ago

Maintenance

Update Backstage to 1.41.1 in #108. Merged 1 month ago

v0.5.0

Maintenance

Update Backstage to 1.41.0. Remove React imports in #102. Merged 3 months ago

v0.4.11

Bug fixes

Correct package.json for the linter package in #96. Merged 6 months ago

v0.4.10

Bug fixes

Patch Spectral source so linting works again in #93. Merged 7 months ago

Maintenance

Update Backstage to 1.36.1 in #93. Merged 7 months ago

Set up Backstage in minutes with Roadie

Focus on using Backstage, rather than building and maintaining it.

Get a demo