apigenie lint
Checks OpenAPI, Swagger 2.0 and AsyncAPI documents, Protobuf files and GraphQL schemas and operations against the rules of a ruleset, reports every issue with its position in the file, and fixes what its rules know how to fix. Each kind of document has a linter of its own, with its own rules, rulesets and configuration. Linter rules lists the rules of all five with what each checks, since which version it exists and the rulesets that turn it on.
Usage
apigenie lint [OPTIONS] FILES...
apigenie lint --fix [OPTIONS] FILES...
apigenie lint --watch [OPTIONS] FILES...
Without options, each file is checked with the recommended ruleset of its linter, or with the
rulesets of the project’s configuration file, and the issues are printed in the stylish format,
which ends with their counts:
apigenie lint api/openapi.yaml
769:12 warning Object schema does not define constraints restricting its size schema-constraints
769:12 error Object schema does not disable additional properties schema-no-additional-properties
781:8 error Schema with integer type does not define proper format schema-format-defined
785:6 warning Unused shared component unused-shared-component
224 issues (32 errors, 192 warnings)
0 errors, 6 warnings are potentially auto-fixable
What the linter checks
A file goes to the linter of its specification, which the linter tells from the root field of a JSON or YAML document, or from the file’s extension:
| File | Recognized by | Rules | Configuration |
|---|---|---|---|
| OpenAPI 3.0, 3.1 or 3.2 | the openapi field of the root; any other JSON or YAML document is read as OpenAPI |
67 (64 before 0.12.0) | commands.lint |
| Swagger 2.0 | the swagger field of the root |
48 | commands.lint.swagger |
| AsyncAPI 3 | the asyncapi field of the root |
39 (34 before 0.12.0) | commands.lint.asyncapi |
| Protobuf (proto3) | the .proto extension |
39 | commands.lint.protobuf |
| GraphQL schemas and operations | the .graphql, .graphqls or .gql extension |
87 | commands.lint.graphql |
A file that cannot be parsed, or that is not a document of its specification, is reported as
Errors reading OpenAPI file 'FILE': (or AsyncAPI, Swagger, Protobuf, GraphQL) with the
position and the message of each error, and the run stops with exit status 2; the files before it
are reported.
Rules and severities
Every rule checks one thing, such as contact-defined
(the info.contact of an OpenAPI document has a name and a way to reach it) or
paths-max-count (the document has at most the given
number of paths). A rule has a severity, error, warning or hint (also written info), which
its ruleset sets and the configuration changes. All three are reported, but only errors fail the
run; hints are suggestions, and do not count as warnings either. A rule reports a hint where its
advice cannot be followed yet, such as
schema-format-deprecated in OpenAPI 3.0
documents. Some rules take options, listed on their pages, such as the number of paths of
paths-max-count.
Rulesets
A ruleset is a named set of rules with their severities and options. Every linter has
recommended, strict, which turns on more rules, and all, every rule of the linter. The OpenAPI linter also has
json-api, the conventions of JSON:API documents, and
privacy, which keeps credentials and personal data out of
URLs and is not part of all; the AsyncAPI linter has
cloudevents, the envelope of CloudEvents messages,
not part of all either; the GraphQL linter has relay,
the Relay Cursor Connections conventions. A configuration lists the rulesets it extends, in
order, and changes rules one by one under rules; see Configuration.
The OpenAPI, AsyncAPI and Swagger linters also extend Spectral ruleset files, by their path (since
0.12.0); see Ruleset files. The OpenAPI and Swagger linters ship with
owasp (since 0.12.0), Spectral’s OWASP API Security Top 10 ruleset,
and the OpenAPI linter with camara, the
CAMARA project’s ruleset.
References to other files
An OpenAPI document may keep parameters, request bodies, responses and other components in other
files, or at URLs. The linter checks what the file holds. A rule about keys, such as
paths-sorted or standard-response-codes, checks a path or a response in another file too; the
other rules skip it. A rule doesn’t report what another file may define: path-parameters-defined
accepts a path parameter that a parameter in another file may define. Lint the other files too, or
lint the document with –bundle to check what the references lead to.
AsyncAPI documents
The 39 rules of the AsyncAPI linter are those of the OpenAPI linter that make sense for AsyncAPI 3
documents (contact-defined, license-defined, operation-tags-defined, unused-shared-component
and others) and rules of its own, such as channel-parameters-defined, channel-addresses-unique
and server-hosts. Since 0.12.0 they include the 5 core rules of the AsyncAPI parser
(asyncapi validate) that the linter lacked: operation-messages-from-channel,
operation-channel-in-channels, channel-servers-in-servers, channel-address-no-query and
latest-version. Custom rules, JavaScript functions, x-apigenie-lint-disable and --fix work
as for OpenAPI documents. OpenAPI and AsyncAPI files can be linted in one run.
Swagger 2.0 documents
The 48 rules of the Swagger linter are those of the OpenAPI linter that make sense for Swagger 2.0
documents (operation-id-unique, parameters-unique, path-parameters-defined,
unused-shared-component and others) and rules of its own: host-defined, schemes-secure,
media-types-defined and swagger-validation, which reports the violations of the Swagger 2.0
specification that span several objects (undefined security schemes, unresolved references,
several body parameters and so on). Custom rules (with oas2 in their formats), JavaScript
functions, x-apigenie-lint-disable and --fix work as for OpenAPI documents.
Protobuf files
The 39 rules of the Protobuf linter check proto3 files for the naming of packages, files, messages,
fields, enums and their values, oneofs, services and methods, for comments on declarations, for
imports (resolved, used, sorted, without cycles, neither public nor weak), for the directory and
version suffix of a package and the consistency of its options across files, for the request and
response names of methods and their streaming, and for spelling. Imports are looked up in the
directories of --proto-path, in the import_paths of the configuration and in the directories
above the importing file. --fix fixes import-used and imports-sorted.
GraphQL documents
The 87 rules of the GraphQL linter check schemas and operations: the type system and operation
rules of the GraphQL specification, naming conventions, descriptions, deprecations, schema design
(root types, mutation inputs and payloads, unreachable types, identifiers), the Relay connection
conventions, ordering and spelling. Operations are checked against a schema, the one of
--graphql-schema or of the schema setting, or else the type system of their own document:
unknown fields, types and arguments, required arguments, deprecated fields and selection depth.
--fix does not change GraphQL files.
Disabling rules in a document
A rule that a part of a document breaks on purpose, because of a legacy decision or work in progress, is disabled in the document itself, as close to that part as possible:
-
In an OpenAPI, Swagger or AsyncAPI document, the
x-apigenie-lint-disableextension of any object, the root included, lists the rules disabled for that object and everything nested in it. Here contact-defined is disabled forinfo, and so for itscontact:info: x-apigenie-lint-disable: - contact-defined -
In a Protobuf file, a comment attached to a declaration (before it, or at the end of its line) with
apigenie-lint-disable rule-a, rule-bdisables the rules for the declaration and everything nested in it; without rule ids it disables every rule. On thesyntaxstatement it covers the whole file. -
In a GraphQL document, a comment
# apigenie-lint-disable rule-a, rule-bbefore a definition disables the rules for it and everything nested in it; without rule ids it disables every rule. The comments at the top of the file that a blank line separates from the first definition, and the comments of theschemadefinition, cover the whole file.
Custom rules honour the extension and the comments like built-in rules.
Custom rules
A rule of the OpenAPI, Swagger or AsyncAPI linter can also be defined in the configuration, under
rules, with an id that is not a built-in rule’s. A custom rule is data, in the format of
Spectral: it selects parts of the document with a
JSONPath expression and checks each of them with a function.
version: "1.0"
commands:
lint:
extends: [recommended]
rules:
operation-summary:
description: Operations must have a summary
message: "{{property}} is missing at {{path}}"
severity: error
given: "$.paths[*][get,put,post,delete,patch]"
then:
field: summary
function: truthy
A rule definition accepts these properties:
| Property | Description |
|---|---|
given |
JSONPath expression, or a list of them, selecting the values to check. Required. |
then |
What to check: an object or a list of objects with function, optional functionOptions and optional field; a message there is ignored (since 0.12.0). Required. |
field |
Narrows each selected value: a member path (summary, a.b[0]), @key to check member names, or a JSONPath expression relative to the value ($.properties[*]). |
message |
Message template; see below. Defaults to description, then to the function’s message. |
description |
Human-readable description of the rule. |
severity |
error, warn (default), info, hint or off. info and hint are reported as hints. |
resolved |
Whether the rule sees the document with local $refs followed. Defaults to true. |
recommended |
false (since 0.12.0) leaves the rule off in a ruleset file extended with recommended (the default), until rules turns it on. Ignored in the configuration’s own rules. |
formats |
Restricts the rule to document formats: oas2 (Swagger 2.0 documents), oas3, oas3_0, oas3_1, oas3_2, or, for AsyncAPI documents, aas3 and aas3_0, aas3_1, … |
Messages may use {{error}} (the function’s message), {{description}},
{{path}} (JSON pointer of the problem), {{property}} (the last path
segment; since 0.12.0, for a path that doesn’t exist, the path from its last existing member in
Spectral’s notation: responses[429].content) and {{value}}. Issues are reported where the
offending value is defined, even when it is reached through a $ref. Custom rules honour
x-apigenie-lint-disable like built-in ones. A custom rule can be switched off
or have its severity changed later in the configuration (my-rule: off), but
it cannot reuse the name of a built-in rule.
JSONPath
given and field expressions follow
RFC 9535 with the extensions Spectral
rulesets commonly use:
- member unions without quotes:
$.paths[*][get,put]; ~at the end selects member names:$.paths[*]~;^selects the parent of what the query has selected so far (since 0.12.0):$.paths..parameters[?(@.name === 'id')]^is the list that holds the parameter. A member name that contains^is written in brackets:$['a^b'];- filters written as JavaScript expressions:
$..[?(@.type === 'object' && !@.properties)], with@property,@parent,@parentProperty,@pathand$, and the string and array methodsmatch,test,startsWith,endsWith,includes,indexOf,toLowerCase,toUpperCase,trimandlength, and, since 0.12.0,constructor.name, which isArray,Object,String,NumberorBoolean:@.type.constructor.name === 'Array'.
Script expressions such as [(@.length-1)] and Spectral aliases (#Name)
are not supported.
Core functions
| Function | Options | Checks that the value… |
|---|---|---|
truthy, falsy |
none | is (not) truthy in the JavaScript sense |
defined, undefined |
none | exists / does not exist |
enumeration |
values |
is one of the listed values |
length |
min, max |
has a length (string, array, object keys, number) within bounds |
pattern |
match, notMatch |
(does not) match a JavaScript regular expression; /re/flags is accepted |
casing |
type (flat, camel, pascal, kebab, cobol, snake, macro), disallowDigits, separator.char, separator.allowLeading |
follows a naming convention |
alphabetical |
keyedBy |
lists keys or items in alphabetical order |
or, xor |
properties |
has at least one / exactly one of the listed members |
schema |
schema, dialect, allErrors |
is valid against a JSON Schema (draft 4 to 2020-12) |
typedEnum |
none | has enum values matching its type |
unreferencedReusableObject |
reusableObjectsLocation |
has only members referenced somewhere in the document |
JavaScript functions
When the core functions are not enough, a function can be written in JavaScript. It is listed
under functions; API Genie loads <name>.js from the functions
directory next to the configuration file (change it with functionsDir).
commands:
lint:
functions: [operationIdPrefix]
rules:
operation-id-prefix:
given: "$.paths[*][*].operationId"
then:
function: operationIdPrefix
functionOptions: { prefix: api }
A function is an ES module whose default export receives the value, the options and a context, and returns a list of problems. The contract is that of Spectral custom functions, so a function written for Spectral works unchanged:
// functions/operationIdPrefix.js
import { createRulesetFunction } from '@stoplight/spectral-core';
import { casing } from '@stoplight/spectral-functions';
export default createRulesetFunction(
{
input: { type: 'string' },
options: {
type: 'object',
properties: { prefix: { type: 'string' } },
required: ['prefix'],
},
},
(input, options, context) => {
if (!input.startsWith(options.prefix)) {
return [{ message: `must start with "${options.prefix}"` }];
}
return casing(input, { type: 'camel' }, context);
},
);
createRulesetFunctionvalidatesfunctionOptionswhen the configuration is loaded and skips values that do not matchinput.- A result may carry a
path, an array of keys and indexes, to point at a more specific location thancontext.path. Since 0.12.0, as in Spectral, a segment of another type, such as a negative number or an array, names the member thatString(value)names. A path to a member that doesn’t exist is reported at the closest member that does. contextprovidespath,rule(name,severity,resolved),document(formats,data) anddocumentInventory:resolved,unresolved, and, since 0.12.0,graph.overallOrder(), each distinct$refvalue of the document once, depth first.console.log,console.info,console.warn,console.errorandconsole.debugprint nothing (since 0.12.0); otherconsolemethods are not defined.- Functions may be
async. - A function that throws is reported as an issue of its rule.
Functions run in a sandbox: they can import other modules from the functions
directory and the two built-in @stoplight modules, but have no access to the
file system, network, processes or timers. Each call must finish within 5
seconds. Custom JavaScript functions are not available in the WebAssembly
build.
Ruleset files
The OpenAPI, AsyncAPI and Swagger linters read Spectral ruleset files (YAML or JSON) since 0.12.0.
extends names one by its path, relative to the configuration file, next to API Genie’s rulesets:
commands:
lint:
extends: [recommended, ./lint/team.spectral.yaml]
rules:
team-no-todo: error
# lint/team.spectral.yaml
extends: ./base.spectral.yaml
functionsDir: ./functions
functions: [noTodo]
rules:
team-path-casing:
given: "$.paths[*]~"
then: { function: pattern, functionOptions: { match: "^(/[a-z-]+)+$" } }
team-no-todo:
recommended: false
given: "$..description"
then: { function: noTodo }
- An entry of
extendsis a path when it starts with./,../,/,.\,..\or\, is an absolute path, or ends in.yaml,.ymlor.json. A file’s ownextends,functionsandfunctionsDirresolve against that file. - The rulesets and the files apply in the order of
extends, each file after what it extends, then the configuration’s ownrules, which can change the severity of a file’s rule or switch it off. [ruleset, mode]chooses how a ruleset’s rules apply.recommended(the default) leaves out definitions withrecommended: false, andallapplies them too.offapplies none, and a rule it defines can still be turned on underrules:team-no-todo: error, ortruefor the severity of its definition. On a built-in ruleset,offleaves it out andallis the same asrecommended.- Files are local: a URL is an error, and so is a file that extends itself. In a ruleset file,
spectral:oas,spectral:asyncapiand npm packages other than@stoplight/spectral-owasp-rulesetare skipped with a warning on the standard error. So are the settings of rules the linter doesn’t have, andaliasesandoverrides. - A file in
extendsapplies to the documents of that section’s linter. A file of –ruleset applies to OpenAPI, AsyncAPI and Swagger documents: give its rulesformatsto keep them to one standard. A top-levelformatsis ignored, as aredescription,documentationUrlandparserOptions; another unknown top-level key is an error. - –ruleset adds a file from the command line.
- The editor and the VS Code extension read ruleset files too, by relative path, without their functions: the editor’s hosts lists what they leave out.
The owasp ruleset
owasp (since 0.12.0) checks OpenAPI and Swagger 2.0 documents for 8 of the 10 risks of the
OWASP API Security Top 10, 2023
edition: API1 to API5 and API7 to API9. Its rules cover numeric ids, authentication schemes,
additional properties, unbounded strings, arrays and integers, rate limits, admin endpoints, URL
parameters, error responses, CORS, plain HTTP and server inventories. It is Spectral’s
@stoplight/spectral-owasp-ruleset 2.0.1,
with its 32 rules and 2 JavaScript functions, and ships with API Genie:
version: '1.0'
commands:
lint:
extends: [recommended, owasp]
swagger:
extends: [recommended, owasp]
With extends: [owasp] alone in apigenie.yaml, apigenie lint openapi.yaml reports 12 issues
on this document:
openapi: 3.1.0
info:
title: Pets
version: 1.0.0
servers:
- url: https://api.example.com
paths:
/pets:
get:
responses:
'200':
description: The pets
content:
application/json:
schema:
type: string
apigenie lint openapi.yaml
6:5 error Declare intended audience of every server by defining servers[0].x-internal as true/false. owasp:api9:2023-inventory-access
9:5 warning This read operation is not protected by any security scheme. owasp:api2:2023-read-restricted
10:7 warning Operation is missing rate limiting response in responses[429]. owasp:api4:2023-rate-limit-responses-429
10:7 warning Operation is missing rate limiting response in responses[429].content. owasp:api4:2023-rate-limit-responses-429
10:7 warning Operation is missing responses[401]. owasp:api8:2023-define-error-responses-401
10:7 warning Operation is missing responses[401].content. owasp:api8:2023-define-error-responses-401
10:7 warning Operation is missing responses[500]. owasp:api8:2023-define-error-responses-500
10:7 warning Operation is missing responses[500].content. owasp:api8:2023-define-error-responses-500
10:7 warning Missing error response of either 400, 422 or 4XX. owasp:api8:2023-define-error-validation
11:9 error All 2XX and 4XX responses should define rate limiting headers. owasp:api4:2023-rate-limit
15:15 error Schema of type string must specify maxLength, enum, or const. owasp:api4:2023-string-limit
15:15 warning Schema of type string should specify a format, pattern, enum, or const. owasp:api4:2023-string-restricted
12 issues (3 errors, 9 warnings)
- Its rules keep Spectral’s ids and severities, and
rulesturns them off or changes their severity as for any other rule.owasp:api7:2023-concerning-url-parameter,infoin Spectral, is reported as a hint. - Each rule applies to the documents Spectral applies it to, also from a ruleset file: none lints
an AsyncAPI document. The rules that read
components.securitySchemes,owasp:api2:2023-no-http-basic,owasp:api2:2023-jwt-best-practicesandowasp:api2:2023-short-lived-access-tokens, report nothing in a Swagger 2.0 document. - A Spectral ruleset file that extends
@stoplight/spectral-owasp-rulesetgets it without a change, ascamaradoes. Inapigenie.yaml, writeowasp. - On 120 of the 121 test documents of the upstream ruleset, it reports the rules, lines and
messages that Spectral reports. On the other, which has an
apiKeysecurity schemein: paththat OpenAPI doesn’t allow, API Genie stops with exit status 2. - The editor and the VS Code extension don’t have it: its functions need JavaScript, which they
don’t run. There, a configuration that extends
owaspgets an error onextendsthat beginsUnknown ruleset owasp, and the documents are linted with the default rules.
| Rule | Severity | Documents |
|---|---|---|
owasp:api1:2023-no-numeric-ids |
error | Swagger 2.0, OpenAPI 3 |
owasp:api2:2023-no-http-basic |
error | Swagger 2.0, OpenAPI 3 |
owasp:api2:2023-no-api-keys-in-url |
error | OpenAPI 3 |
owasp:api2:2023-no-credentials-in-url |
error | OpenAPI 3 |
owasp:api2:2023-auth-insecure-schemes |
error | OpenAPI 3 |
owasp:api2:2023-jwt-best-practices |
error | Swagger 2.0, OpenAPI 3 |
owasp:api2:2023-short-lived-access-tokens |
error | Swagger 2.0, OpenAPI 3 |
owasp:api2:2023-write-restricted |
error | Swagger 2.0, OpenAPI 3 |
owasp:api2:2023-read-restricted |
warning | Swagger 2.0, OpenAPI 3 |
owasp:api3:2023-no-additionalProperties |
warning | OpenAPI 3.0 |
owasp:api3:2023-constrained-additionalProperties |
warning | OpenAPI 3.0 |
owasp:api3:2023-no-unevaluatedProperties |
warning | OpenAPI 3.1 |
owasp:api3:2023-constrained-unevaluatedProperties |
warning | OpenAPI 3.1 |
owasp:api4:2023-rate-limit |
error | OpenAPI 3 |
owasp:api4:2023-rate-limit-retry-after |
error | OpenAPI 3 |
owasp:api4:2023-rate-limit-responses-429 |
warning | Swagger 2.0, OpenAPI 3 |
owasp:api4:2023-array-limit |
error | Swagger 2.0, OpenAPI 3 |
owasp:api4:2023-string-limit |
error | Swagger 2.0, OpenAPI 3 |
owasp:api4:2023-string-restricted |
warning | Swagger 2.0, OpenAPI 3 |
owasp:api4:2023-integer-limit |
error | OpenAPI 3.1 |
owasp:api4:2023-integer-limit-legacy |
error | Swagger 2.0, OpenAPI 3.0 |
owasp:api4:2023-integer-format |
error | Swagger 2.0, OpenAPI 3 |
owasp:api5:2023-admin-security-unique |
error | Swagger 2.0, OpenAPI 3 |
owasp:api7:2023-concerning-url-parameter |
hint | Swagger 2.0, OpenAPI 3 |
owasp:api8:2023-define-cors-origin |
error | Swagger 2.0, OpenAPI 3 |
owasp:api8:2023-no-scheme-http |
error | Swagger 2.0 |
owasp:api8:2023-no-server-http |
error | OpenAPI 3 |
owasp:api8:2023-define-error-validation |
warning | Swagger 2.0, OpenAPI 3 |
owasp:api8:2023-define-error-responses-401 |
warning | Swagger 2.0, OpenAPI 3 |
owasp:api8:2023-define-error-responses-500 |
warning | Swagger 2.0, OpenAPI 3 |
owasp:api9:2023-inventory-access |
error | OpenAPI 3 |
owasp:api9:2023-inventory-environment |
error | OpenAPI 3 |
The camara ruleset
camara (since 0.12.0) is the ruleset the CAMARA project lints its
APIs with, for Commonalities r4. It is the .spectral-r4.yaml file of
camaraproject/tooling as of 4
November 2026, with its 41 rules and 14 JavaScript functions. It ships with API Genie, so nothing
needs to be copied into the repository:
version: '1.0'
commands:
lint:
extends: [camara]
- Its rules keep their ids (
camara-properties-descriptions), andruleschanges them as it changes any other rule. Two of them arerecommended: false:[camara, all]also applies the deprecatedcamara-discriminator-use, andcamara-language-avoid-telco, whose function only logs to the console and so reports nothing.[camara, off]applies none. - Upstream, the file also extends
@stoplight/spectral-owasp-ruleset, which isowasphere: its rules apply with CAMARA’s settings, which turn 15 of them off, make 4 warnings and makeowasp:api8:2023-define-error-responses-401an error. It extendsspectral:oastoo, which API Genie doesn’t have: those rules don’t run, and nothing is reported about it. The file’s settingoperation-success-response: trueturns on API Genie’s rule of that id, as a warning. Addrecommendednext to it for API Genie’s other checks:extends: [recommended, camara]. - A ruleset file can extend it too (
extends: [camara]), which lints with it under--no-config --ruleset FILE.--rulesetitself always names a file. - CAMARA’s APIs reference
CAMARA_common.yamland its other common files: lint them withbundle: truein the configuration, or –bundle, so that the rules check what the references lead to. - The editor and the VS Code extension don’t have it: its functions need JavaScript, which they
don’t run. There, a configuration that extends
camaragets an error onextendsthat beginsUnknown ruleset camara, and the documents are linted with the default rules. - Lint CAMARA APIs sets up a CAMARA repository, its pull requests included.
Fixing
--fix fixes what the rules know how to fix and writes the files back under their names: the
rules marked auto-fixable on their pages, 19 of the OpenAPI linter, 18 of the Swagger linter, 11
of the AsyncAPI linter and 2 of the Protobuf linter (import-used and imports-sorted). The
YAML comments of a fixed OpenAPI, Swagger or AsyncAPI document stay with the values they belong to,
and those of a value a fix removes go with it; --strip-comments drops them instead. A Protobuf
file is fixed by editing its text, which keeps everything outside the edited declarations. Files
without fixes are not rewritten. The exit status counts the issues that remain after the fixes.
Formatters
--formatter NAME chooses how the issues are written to standard output. The formats are those of
ESLint’s formatters, with SARIF added, so that tools which read ESLint reports read these too. Every format sorts the issues by
file, then by line and column. checkstyle, html, json, junit, sarif and tap write one
document for the whole run, reported at the end; compact, stylish, unix and visualstudio
report each file as soon as it is linted.
checkstyle
The Checkstyle XML format.
<?xml version="1.0" encoding="utf-8"?>
<checkstyle version="4.3">
<file name="/apigenie/data/openapi.yaml">
<error line="2" column="2" severity="error" message="Info summary is missing or empty" source="info-defined"/>
<error line="12" column="4" severity="warning" message="Tag 'Articles' has no meaningful description defined" source="tag-description-defined"/>
<error line="13" column="4" severity="warning" message="Tag 'Comments' has no meaningful description defined" source="tag-description-defined"/>
<error line="14" column="4" severity="warning" message="Tag 'Favorites' has no meaningful description defined" source="tag-description-defined"/>
<error line="15" column="4" severity="warning" message="Tag 'Profile' has no meaningful description defined" source="tag-description-defined"/>
</file>
</checkstyle>
compact
The default output of JSHint: one line per issue.
/apigenie/data/openapi.yaml: line 2, col 2, Error - Info summary is missing or empty. (info-defined)
/apigenie/data/openapi.yaml: line 12, col 4, Warning - Tag 'Articles' has no meaningful description defined. (tag-description-defined)
/apigenie/data/openapi.yaml: line 13, col 4, Warning - Tag 'Comments' has no meaningful description defined. (tag-description-defined)
/apigenie/data/openapi.yaml: line 14, col 4, Warning - Tag 'Favorites' has no meaningful description defined. (tag-description-defined)
/apigenie/data/openapi.yaml: line 15, col 4, Warning - Tag 'Profile' has no meaningful description defined. (tag-description-defined)
html
One HTML file, with the counts and a table of the issues, one row each, linking to the pages of the rules.
<!DOCTYPE html>
<html>
<body>
<section id="overview">
<h1>API Genie Report</h1>
<ul>
<li>Total: 224</li>
<li>Errors: 32</li>
<li>Warnings: 192</li>
</ul>
</section>
<section id="issues">
<table>
<caption>/apigenie/data/openapi.yaml</caption>
<tr>
<td class="pos">2:2</td>
<td class="error">Error</td>
<td>Info summary is missing or empty</td>
<td>
<a href="https://apigenie.pl/docs/linter/openapi/rules/info-defined">info-defined</a>
</td>
</tr>
<tr>
<td class="pos">12:4</td>
<td class="warning">Warning</td>
<td>Tag 'Articles' has no meaningful description defined</td>
<td>
<a href="https://apigenie.pl/docs/linter/openapi/rules/tag-description-defined">tag-description-defined</a>
</td>
</tr>
</table>
</body>
</html>
json
A JSON report, for scripts. results has one item per file with issues; formatVersion is the
version of the format, which changes only when a member is removed or changes meaning (see
Compatibility). Its JSON Schema is
apigenie-lint-report.json. API Genie 0.9
and earlier wrote the bare results array.
{
"formatVersion": 1,
"results": [
{
"filePath": "/apigenie/data/openapi.yaml",
"messages": [
{
"column": 2,
"line": 2,
"message": "Info summary is missing or empty",
"ruleId": "info-defined",
"severity": "error"
},
{
"column": 4,
"line": 12,
"message": "Tag 'Articles' has no meaningful description defined",
"ruleId": "tag-description-defined",
"severity": "warning"
},
... more issues ...
]
}
]
}
junit
The format of the JUnit Jenkins plugin: a test suite per file, a test case per issue.
<?xml version="1.0" encoding="utf-8"?>
<testsuites>
<testsuite package="apigenie" time="0" tests="224" errors="224" name="/apigenie/data/openapi.yaml">
<testcase time="0" name="apigenie.info-defined" classname="apigenie.info-defined">
<failure message="Info summary is missing or empty"><![CDATA[line 2, col 2, Error - Info summary is missing or empty. (info-defined)]]></failure>
</testcase>
<testcase time="0" name="apigenie.tag-description-defined" classname="apigenie.tag-description-defined">
<failure message="Tag 'Articles' has no meaningful description defined"><![CDATA[line 12, col 4, Warning - Tag 'Articles' has no meaningful description defined. (tag-description-defined)]]></failure>
</testcase>
<testcase time="0" name="apigenie.tag-description-defined" classname="apigenie.tag-description-defined">
<failure message="Tag 'Comments' has no meaningful description defined"><![CDATA[line 13, col 4, Warning - Tag 'Comments' has no meaningful description defined. (tag-description-defined)]]></failure>
</testcase>
</testsuite>
</testsuites>
sarif
SARIF 2.1.0, the format of
GitHub code scanning and other static analysis dashboards. Files below the current directory are
given relative to it (%SRCROOT%), so that code scanning finds them in the repository. A result
whose JSON pointer is known has it as a logical location and in a fingerprint, which lets code
scanning keep tracking the issue when lines move.
{
"$schema": "https://json.schemastore.org/sarif-2.1.0.json",
"version": "2.1.0",
"runs": [
{
"tool": {
"driver": {
"name": "apigenie",
"informationUri": "https://apigenie.pl",
"rules": [
{
"id": "info-defined",
"helpUri": "https://apigenie.pl/docs/linter/openapi/rules/info-defined"
},
... more rules ...
]
}
},
"originalUriBaseIds": {
"%SRCROOT%": { "uri": "file:///apigenie/" }
},
"results": [
{
"ruleId": "info-defined",
"ruleIndex": 0,
"level": "error",
"message": { "text": "Info summary is missing or empty" },
"locations": [
{
"physicalLocation": {
"artifactLocation": { "uri": "data/openapi.yaml", "uriBaseId": "%SRCROOT%" },
"region": { "startLine": 2, "startColumn": 2 }
},
"logicalLocations": [
{ "fullyQualifiedName": "#/info", "kind": "member" }
]
}
],
"partialFingerprints": {
"apigenieLocation/v1": "info-defined|data/openapi.yaml|#/info"
}
},
... more issues ...
]
}
]
}
stylish
The default: a table per file, with the position, the severity, the message and the rule of each issue, coloured on a terminal, and the counts at the end.
764:6 warning Unused shared component unused-shared-component
769:12 warning Object schema does not define constraints restricting its size schema-constraints
769:12 error Object schema does not disable additional properties schema-no-additional-properties
777:6 warning Unused shared component unused-shared-component
781:8 error Schema with integer type does not define proper format schema-format-defined
781:8 warning Integer schema does not define constraints restricting its range schema-constraints
785:6 warning Unused shared component unused-shared-component
789:8 error Schema with integer type does not define proper format schema-format-defined
789:8 warning Integer schema does not define constraints restricting its range schema-constraints
795:6 warning Unused shared component unused-shared-component
224 issues (32 errors, 192 warnings)
0 errors, 6 warnings are potentially auto-fixable
tap
Test Anything Protocol version 14: one test per file, with the issues as its YAML diagnostics.
TAP version 14
1..1
not ok - /apigenie/data/openapi.yaml
---
errorCount: 32
issues:
- column: 2
line: 2
message: Info summary is missing or empty
ruleId: info-defined
severity: error
- column: 4
line: 12
message: Tag 'Articles' has no meaningful description defined
ruleId: tag-description-defined
severity: warning
- column: 4
line: 13
message: Tag 'Comments' has no meaningful description defined
ruleId: tag-description-defined
severity: warning
unix
One line per issue in the file:line:column: message form of Unix tools, for grep and awk.
/apigenie/data/openapi.yaml:2:2: Info summary is missing or empty. [Error/info-defined]
/apigenie/data/openapi.yaml:12:4: Tag 'Articles' has no meaningful description defined. [Warning/tag-description-defined]
/apigenie/data/openapi.yaml:13:4: Tag 'Comments' has no meaningful description defined. [Warning/tag-description-defined]
/apigenie/data/openapi.yaml:14:4: Tag 'Favorites' has no meaningful description defined. [Warning/tag-description-defined]
/apigenie/data/openapi.yaml:15:4: Tag 'Profile' has no meaningful description defined. [Warning/tag-description-defined]
/apigenie/data/openapi.yaml:16:4: Tag 'Tags' has no meaningful description defined. [Warning/tag-description-defined]
visualstudio
The form the integrated terminal of Visual Studio turns into clickable errors.
/apigenie/data/openapi.yaml(2,2): error info-defined : Info summary is missing or empty.
/apigenie/data/openapi.yaml(12,4): warning tag-description-defined : Tag 'Articles' has no meaningful description defined.
/apigenie/data/openapi.yaml(13,4): warning tag-description-defined : Tag 'Comments' has no meaningful description defined.
/apigenie/data/openapi.yaml(14,4): warning tag-description-defined : Tag 'Favorites' has no meaningful description defined.
/apigenie/data/openapi.yaml(15,4): warning tag-description-defined : Tag 'Profile' has no meaningful description defined.
/apigenie/data/openapi.yaml(16,4): warning tag-description-defined : Tag 'Tags' has no meaningful description defined.
Options
–config FILE
The configuration file. Without it, the first of apigenie.yaml, apigenie.yml, apigenie.json,
.apigenie.yaml, .apigenie.yml and .apigenie.json found in the current directory or its
parents, up to the root of the git repository, is read. See Configuration.
apigenie lint --config api-style-guide.yaml api/*.yaml
–no-config
Lints without looking for a configuration file: with the recommended ruleset of each linter, or,
for the OpenAPI, AsyncAPI and Swagger linters, with the files of --ruleset instead.
–ruleset FILE
A Spectral ruleset file that OpenAPI, AsyncAPI and Swagger documents are linted with (since
0.12.0). It applies after the rulesets of the configuration’s extends and before its rules,
which can re-tune the file’s rules. Without a configuration file, and for a linter whose
section is missing, it replaces recommended. The path is relative to the current directory, and
always names a file, whatever its name: a file that doesn’t end in .json is read as YAML. Can be
repeated; see Ruleset files.
apigenie lint --no-config --ruleset .spectral.yaml api/openapi.yaml
–fix
Fixes the issues the rules know how to fix and writes the files back; see Fixing. The exit status counts the issues that remain.
apigenie lint --fix api/openapi.yaml
–bundle
Bundles the local files an OpenAPI 3.x document references into it before linting, as
bundle does, so that the rules check what the references lead to. An
issue in bundled content is reported in the file it comes from, at its line. A reference to a URL
can’t be bundled: the command reports it and exits with status 2. --bundle can’t be combined with
--fix, which would write the bundled document to the file. Swagger and AsyncAPI files are linted as
they are. To bundle on every run except under --fix, set bundle: true in the
configuration.
apigenie lint --bundle api/openapi.yaml
–strip-comments
With --fix, drops the YAML comments of the OpenAPI, Swagger and AsyncAPI documents it rewrites
instead of keeping them.
–watch
Keeps running, and lints again whenever an input file, the configuration file, a ruleset file, a
JavaScript function file or a GraphQL schema file changes. A ruleset file that can’t be read or
parsed is watched too, so fixing it lints again. Each run is preceded by a Changed: PATH line for
every changed file on standard error, so that the reports on standard output stay parseable. The
command never exits because of issues.
apigenie lint --watch --formatter compact api/*.yaml
–formatter NAME
The format of the report: checkstyle, compact, html, json, junit, sarif, stylish
(the default), tap, unix or visualstudio; see Formatters.
apigenie lint --formatter sarif api/openapi.yaml > lint.sarif
–proto-path DIR
A directory in which the imports of .proto files are looked up, before the import_paths of the
configuration and the directories above the importing file. Can be repeated.
apigenie lint --proto-path proto --proto-path third_party proto/acme/**/*.proto
–graphql-schema FILE
A GraphQL schema file that the operations and fragments of the linted GraphQL files are checked
against. Can be repeated for a schema split across files. When given, it replaces the files of
the schema setting of the configuration; relative paths resolve against the current
directory. With --watch, the schema files are watched too.
apigenie lint --graphql-schema schema.graphql queries/*.graphql
Exit status
| Status | When |
|---|---|
| 0 | No issue of severity error was reported; warnings and hints do not count. With --fix, no error remains after the fixes. |
| 1 | At least one error was reported, or remains after the fixes of --fix. |
| 2 | The configuration, a ruleset file or an input file cannot be read or parsed or is invalid, a ruleset is a URL or a ruleset file extends itself, or an input is not a document of its specification. The files before it are reported. --fix is combined with --bundle: no file is linted. |
With --watch the command keeps running and never exits because of issues. See the
exit statuses shared by the commands.
Configuration
The settings live under commands.lint of the configuration file.
The keys of the section configure the OpenAPI linter; its asyncapi, swagger, protobuf and
graphql sections configure the other linters, each with its own rules. Without a configuration
file, and for every linter whose section is missing, the recommended ruleset applies, as if the
configuration were the one below. For the OpenAPI, AsyncAPI and Swagger linters, the files of
–ruleset replace it.
version: "1.0"
commands:
lint:
extends: [recommended]
| Key | Linter | Keys |
|---|---|---|
extends |
OpenAPI | The rulesets and ruleset files to combine, in order |
rules |
OpenAPI | The settings of single rules, and custom rules |
functions |
OpenAPI | The JavaScript functions of custom rules |
functionsDir |
OpenAPI | Their directory, functions next to the configuration file |
bundle |
OpenAPI | Whether to bundle the local files a document references first |
asyncapi |
AsyncAPI | extends, rules, functions, functionsDir |
swagger |
Swagger | extends, rules, functions, functionsDir |
protobuf |
Protobuf | extends, rules, import_paths |
graphql |
GraphQL | extends, rules, self_contained, schema |
Example - The recommended rules, with one rule turned off, the severity of one changed, and the options of two set
version: "1.0"
commands:
lint:
extends:
- recommended
rules:
info-defined: off
paths-max-count:
- error
- 30
schema-datetime-suffix:
- error
- At
tags-unique: error
bundle: true (since 0.12.0) bundles the local files an OpenAPI 3.x document references into it
before linting, on every run, as –bundle does. The default is false, and then
--bundle bundles for one run. --fix ignores the key: it lints and fixes each file as it is. The
editor and the VS Code extension ignore bundle too: they lint what each file holds.
Example - A CAMARA repository, whose APIs reference its common files
version: "1.0"
commands:
lint:
extends: [recommended, camara]
bundle: true
The formats that the format rules accept come from the format registry, which openapi.custom_formats extends for every linter of JSON and YAML documents.
extends
The rulesets whose rules, severities and options make up the starting point, in the order they are
applied: when two rulesets set the same rule, the later one wins. The names are those of the
ruleset pages of the linter (OpenAPI, AsyncAPI,
Swagger 2.0, Protobuf,
GraphQL). For the OpenAPI, AsyncAPI and Swagger linters, an entry can also
be (since 0.12.0) a Spectral ruleset file, by its path relative to the configuration file, or a
[ruleset, recommended|all|off] pair; see Ruleset files. For the OpenAPI and
Swagger linters, an entry can also be (since 0.12.0) owasp, and for the
OpenAPI linter camara; both ship with API Genie.
rules
The settings of single rules, applied over the rulesets, by rule id. A setting is one of:
- a severity:
offdisables the rule;warning(alsowarn),error(err) andhint(info) enable it with that severity false, which disables the rule, ortrue, which enables it with its current severity- a two-element array
[severity, options]: an active severity and the options of the rule, described on its page - for an id that is not a built-in rule’s, the definition of a custom rule (OpenAPI, Swagger and AsyncAPI linters)
Example - paths-max-count reports an error above
30 paths, and info-defined is off
version: "1.0"
commands:
lint:
rules:
info-defined: off
paths-max-count:
- error
- 30
asyncapi
The configuration of the AsyncAPI linter: extends, rules, functions and functionsDir as
above, with the ids of the AsyncAPI rules. The OpenAPI settings of
commands.lint do not apply to AsyncAPI documents.
version: "1.0"
commands:
lint:
extends: [recommended]
asyncapi:
extends: [strict]
rules:
parameter-naming: [warning, camelCase]
server-hosts: off
swagger
The configuration of the Swagger linter: extends, rules, functions and functionsDir as
above, with the ids of the Swagger 2.0 rules. The OpenAPI settings of
commands.lint do not apply to Swagger documents.
version: "1.0"
commands:
lint:
extends: [recommended]
swagger:
extends: [strict]
rules:
schemes-secure: [error, { upgradeInsecure: true }]
swagger-validation: [error, { checks: [unresolved-reference, security-scheme-defined] }]
paths-sorted: off
protobuf
The configuration of the Protobuf linter: extends and rules as above, with the ids of the
Protobuf rules, and import_paths, the directories searched for imported
files after those of --proto-path; relative paths resolve against the directory of the
configuration file.
version: "1.0"
commands:
lint:
protobuf:
extends: [strict]
import_paths: [proto, third_party]
rules:
enum-zero-value-suffix: [error, _UNKNOWN]
rpc-no-client-streaming: off
graphql
The configuration of the GraphQL linter: extends and rules as above, with the ids of the
GraphQL rules, self_contained (whether each document holds every type
and fragment it references, so that references to missing ones are reported; false by default)
and schema (a path, or a list of paths, of the schema files operations are checked against;
relative paths resolve against the directory of the configuration file;
–graphql-schema replaces them). Without schema, operations are checked
against the type system of their own document.
version: "1.0"
commands:
lint:
graphql:
extends: [recommended, relay]
schema: schema.graphql
rules:
field-description-defined: warning
selection-set-depth: [error, { maxDepth: 5 }]
no-deprecated: off
See also
- Linter rules: Every rule of the five linters, and the rulesets.
- Configuration: The configuration file, and where it is looked for.
- format: Lays out the documents the linter checks.
- GitHub Action: Runs
apigenie lintin a workflow.