https://github.com/zalando/backstage-plugin-api-linter
API Linter is a quality assurance tool that checks the compliance of API's specifications to Zalando's API rules.
https://github.com/zalando/backstage-plugin-api-linter
Last synced: 3 months ago
JSON representation
API Linter is a quality assurance tool that checks the compliance of API's specifications to Zalando's API rules.
- Host: GitHub
- URL: https://github.com/zalando/backstage-plugin-api-linter
- Owner: zalando
- License: mit
- Created: 2022-06-30T12:00:36.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2023-03-25T12:22:01.000Z (over 3 years ago)
- Last Synced: 2025-10-23T18:53:32.420Z (8 months ago)
- Language: TypeScript
- Homepage:
- Size: 890 KB
- Stars: 15
- Watchers: 4
- Forks: 3
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# backstage-plugin-api-linter
Welcome to the Backstage Plugin API Linter!
API Linter is a quality assurance tool. Its main purpose is to check the compliance of API's specifications to Zalando's
API rules.
The plugin's UI is able to lint the API specification in OpenAPI format. The result of the linting is a set of
Violations. A violation contains information about the violated rule, its severity, and path of the violation in the
specification document.
This plugin is an UI using [Zally](https://github.com/zalando/zally) as a backend.
## Getting started
Add the plugin to your frontend app:
```
cd packages/app && yarn add backstage-plugin-api-linter
```
On your `app-config.yaml` configure the proxy endpoint of the plugin.
```yaml
proxy:
'/api-linter':
target:
allowedHeaders: ['Authorization']
```
#### Using ApiLinter:
First export the plugin on `app/App.tsx` file:
```js
export { APILinterPlugin } from 'backstage-plugin-api-linter';
```
Then use the component on your application!
With [tabbed layout](https://backstage.io/storybook/?path=/story/navigation-tabbedlayout--default):
```jsx
```
Content
```javascript
```
## Running the plugin locally
Follow these steps to run the plugin locally for development:
1. Start Zally locally using Docker.
- Please follow the official Zally instructions here: https://github.com/zalando/zally
2. Install dependencies for the local backend server (it mimics the Backstage backend by proxying requests to Zally):
```bash
yarn --cwd dev install
```
3. Run the development environment (this starts both the frontend and the local backend concurrently):
```bash
yarn dev
```
## How to track user behaviour
We are currently using Google Analytics for tracking the user behavior.
To track the plugin you can pass your google Analytics functions as props to the `APILinter` component.
```jsx
```
#### where
- sendEvent is:
```javascript
function sendEvent(args: IEventTracking) {
GoogleAnalytics.event({
plugin: args.plugin,
category: args.eventCategory,
action: args.eventAction,
label: args.eventLabel,
});
}
```
```ts
interface IEventTracking {
plugin: string;
eventLabel: string;
eventAction: string;
eventCategory: string;
}
```
- sendPageView is:
```javascript
function sendPageView() {
GoogleAnalytics.set({ page: window.location.pathname });
GoogleAnalytics.pageview(window.location.pathname + window.location.search);
}
```
- eventInfo is:
```ts
interface ICommonEventInfo {
plugin: string;
eventCategory: string;
}
```
eventInfo will be the same for all events
#### Tracked events are:
- page view
- clicks on Zalando's guideline link
- clicks on import url
- hover on url input
- validate by url
- cancel validate by url
- clicks on schema input
- validate by schema input
- clicks to view rules
- clicks on individual rule cards
- clicks on tags (must, should, may)
- clicks on links on rule cards
- clicks on validate by schema button
- hovers on api badge
- hovers on api badge text
## Committing changes and releases
This repository uses Conventional Commits and semantic-release to automate versioning and publishing. Follow these steps when committing:
- Use the guided commit prompt: run `yarn commit` instead of `git commit`.
- This launches Commitizen and helps you compose a valid conventional commit message (e.g., `feat: add new rule`, `fix: handle empty spec`).
- Do not bump the version in package.json manually.
- The version is managed by semantic-release and is intentionally set to `0.0.0-semantic-release`. The real version is calculated from git history and applied during release.
How versioning works with semantic-release:
- A commit of type `fix:` (or `perf:`) triggers a patch release (e.g., 1.0.12 → 1.0.13).
- A commit of type `feat:` triggers a minor release (e.g., 1.0.12 → 1.1.0).
- Any commit that declares a breaking change (footer `BREAKING CHANGE:` or an exclamation mark after type, like `feat!: ...`) triggers a major release (e.g., 1.x → 2.0.0).
- Other types like `docs:`, `chore:`, `test:` generally do not trigger a release unless they include a breaking change note.
Previewing a release for your PR:
- Our Verify workflow on pull requests runs `yarn release --dry-run` and posts logs under the PR Checks.
- Open your PR → Checks → Verify → look for the "Semantic release (dry run)" step to see whether a release would occur and what the next version would be.