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.
Installation Instructions
These instructions apply to self-hosted Backstage only.
Install the package
- From the Backstage root run
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
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
// inside your <EntityLayout> for API entities
<EntityLayout.Route
if={isApiDocsSpectralLinterAvailable}
path="/linter"
title="Linter"
>
<EntityApiDocsSpectralLinterContent />
</EntityLayout.Route>
A common pattern looks like this
// 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
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
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, and based on the code located here. 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.