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-disable extension of any object, the root included, lists the rules disabled for that object and everything nested in it. Here contact-defined is disabled for info, and so for its contact:

    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-b disables the rules for the declaration and everything nested in it; without rule ids it disables every rule. On the syntax statement it covers the whole file.

  • In a GraphQL document, a comment # apigenie-lint-disable rule-a, rule-b before 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 the schema definition, 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, @path and $, and the string and array methods match, test, startsWith, endsWith, includes, indexOf, toLowerCase, toUpperCase, trim and length, and, since 0.12.0, constructor.name, which is Array, Object, String, Number or Boolean: @.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);
  },
);
  • createRulesetFunction validates functionOptions when the configuration is loaded and skips values that do not match input.
  • A result may carry a path, an array of keys and indexes, to point at a more specific location than context.path. Since 0.12.0, as in Spectral, a segment of another type, such as a negative number or an array, names the member that String(value) names. A path to a member that doesn’t exist is reported at the closest member that does.
  • context provides path, rule (name, severity, resolved), document (formats, data) and documentInventory: resolved, unresolved, and, since 0.12.0, graph.overallOrder(), each distinct $ref value of the document once, depth first.
  • console.log, console.info, console.warn, console.error and console.debug print nothing (since 0.12.0); other console methods 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 extends is a path when it starts with ./, ../, /, .\, ..\ or \, is an absolute path, or ends in .yaml, .yml or .json. A file’s own extends, functions and functionsDir resolve against that file.
  • The rulesets and the files apply in the order of extends, each file after what it extends, then the configuration’s own rules, 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 with recommended: false, and all applies them too. off applies none, and a rule it defines can still be turned on under rules: team-no-todo: error, or true for the severity of its definition. On a built-in ruleset, off leaves it out and all is the same as recommended.
  • Files are local: a URL is an error, and so is a file that extends itself. In a ruleset file, spectral:oas, spectral:asyncapi and npm packages other than @stoplight/spectral-owasp-ruleset are skipped with a warning on the standard error. So are the settings of rules the linter doesn’t have, and aliases and overrides.
  • A file in extends applies to the documents of that section’s linter. A file of –ruleset applies to OpenAPI, AsyncAPI and Swagger documents: give its rules formats to keep them to one standard. A top-level formats is ignored, as are description, documentationUrl and parserOptions; 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 rules turns them off or changes their severity as for any other rule. owasp:api7:2023-concerning-url-parameter, info in 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-practices and owasp:api2:2023-short-lived-access-tokens, report nothing in a Swagger 2.0 document.
  • A Spectral ruleset file that extends @stoplight/spectral-owasp-ruleset gets it without a change, as camara does. In apigenie.yaml, write owasp.
  • 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 apiKey security scheme in: path that 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 owasp gets an error on extends that begins Unknown 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), and rules changes them as it changes any other rule. Two of them are recommended: false: [camara, all] also applies the deprecated camara-discriminator-use, and camara-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 is owasp here: its rules apply with CAMARA’s settings, which turn 15 of them off, make 4 warnings and make owasp:api8:2023-define-error-responses-401 an error. It extends spectral:oas too, which API Genie doesn’t have: those rules don’t run, and nothing is reported about it. The file’s setting operation-success-response: true turns on API Genie’s rule of that id, as a warning. Add recommended next 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. --ruleset itself always names a file.
  • CAMARA’s APIs reference CAMARA_common.yaml and its other common files: lint them with bundle: true in 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 camara gets an error on extends that begins Unknown 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 &apos;Articles&apos; has no meaningful description defined" source="tag-description-defined"/>
        <error line="13" column="4" severity="warning" message="Tag &apos;Comments&apos; has no meaningful description defined" source="tag-description-defined"/>
        <error line="14" column="4" severity="warning" message="Tag &apos;Favorites&apos; has no meaningful description defined" source="tag-description-defined"/>
        <error line="15" column="4" severity="warning" message="Tag &apos;Profile&apos; 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 &apos;Articles&apos; 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 &apos;Comments&apos; 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: off disables the rule; warning (also warn), error (err) and hint (info) enable it with that severity
  • false, which disables the rule, or true, 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 lint in a workflow.
Was this helpful?