paypal / openapilint

Node.js linter for OpenAPI specs

openapilint

This project uses Node.js to implement an OpenAPI linter. As with any linter, there are configurable options for validating your OpenAPI specs.

Install openapilint

npm install openapilint --save

Usage

openapilint takes as input a json schema, and json config object:

const schema = {
  info: {
    description: 'handy description'
  }
};
const config = {
  "rules": {
    "docs-path": true,  // rule will be run, and has no special config
    "no-restricted-words": {"words": ["supersecretacronym"]},  // rule will be run with the specified config
    "root-tags": false // rule will not be run
  }
};

and returns a promise of the results:

const result = new OpenApiLint(config).lint(schema);

return result.then((lintResult) => {
  // Do something with the result Map.
}).catch((error) => {
  // Do something with the Error.
});

lintResult is a String -> RuleResult immutable Map of nested immutable objects for consumption. Specifically:

• RuleResult is a String -> Object immutable Record with two keys, description (String) & failures (List<RuleFailure>).
• RuleFailure is a String -> String immutable Record with two keys, location (String) & hint (String)

It is up to the implementer to parse this data and provide a useful error response to the user.

Rules

By default, only the rules in lib/rules are supported. Details of these rules can be found in docs/rules.

Dereferencing

Due to the complex nature of multi-file references, openapilint rules assume that all references are contained within the input. For simplicity, references to anything other than internally are treated as errors.

OpenAPI supported versions

openapilint supports Swagger 2.0. Support for OpenAPI 3.0 is not planned.

Comparison to other validators

openapilint does have some overlapping features with other json validators, such as joi and jsonschema. A developer using this project may choose to use those validators as a first wave of checks against a particular spec before running it through the openapilint set of rules. This is expected and encouraged. The rules implemented within openapilint go above and beyond those validators by targeting the common OpenAPI-specific problems.

License

See License.

Contributing

See Contributing.

Acknowledgements

This project was inspired by - and heavily influenced by - eslint, markdownlint, and swagger-api-checkstyle. The configuration schema and some code was modified for usage in this project.

openapilint's Issues

[Rule] Produces/Consumes must be present

produces and consumes should never be optional at the root level. This rule validates that it always exists.

[Rule] Ensure no orphan objects

Similar to OpenAPI-Lint's (another project with a similar name) references checker, the requirement is to ensure there are no orphan reference objects. This will require crawling the entire schema to find which ones are indeed referenced.

[Rule] Enforce a unique custom id for SDK generation

Fields used in class names for SDKs will need to be present for certain types of fields. This rule will need to specify those fields, and the parameter name, such as x-publicSDKClassName.

[Engine] To avoid multi-file problems, a full dereference is not required

What is required is a completely self-contained spec (i.e. one whose $refs only point to locations within the current JSON document). While chasing those $refs do provide a few challenges, it is better to overcome those than work against incomplete specs.

This claim refers to this part of the readme:

Due to the complex nature of multi-file references, openapilint rules assume that a schema is fully dereferenced as much as possible. It is up to you to dereference the schema before passing it as input.

If time allows, I will try to add this functionality.

Cleanup no-restricted-words

no-restricted-words is lacking some things, and is not quite correct. Specifically:

1. It is not case insensitive
2. It does not parse $refs and all the right schema objects.
3. It matches any string, instead of exact words.

[Rule(s)] Add rules found in swagger-api-checkstyle

This project should handle all functionality in swagger-api-checkstyle.

[Rule] Path parameters must have 'required = true'

According to swagger docs: The parameter name must be the same as specified in the path. Also remember to add required: true, because path parameters are always required.

[Rule] Remove legacy docs-path

The docs-path rule includes a vendor extension. For this project to be general purpose, we should eliminate this last vendor extension rule.

[Rule] Allow markdown linting within fields that support markdown

The same markdown fields where we detect no-restricted-words can also be checked against markdownlint. All config would be passed through to markdownlint.

Inline config example:

{
  "markdownlint": {
    "default": true,
    "MD003": { "style": "atx_closed" },
    "MD007": { "indent": 4 },
    "no-hard-tabs": false,
    "whitespace": false
  }
}

Add 'recommendedAlternative' config to *-custom rules.

It would be nice if the custom rules have an additional config, recommendedAlternative, which suggests how one might correct an error in limited cases.

[Engine] Add other $ref parsing

The main schema object $refs work properly, but there are still some gaps with less used $refs. These include:

• Path Item Objects
• Parameter Definition Objects
• Response Definition Objects
• Security Definition Objects

[Rule] Enforce string property constraints

String properties MUST have at least one of the following constraints:

1. maxLength (if present, should also have minLength and pattern)
2. enum

Additionally, readOnly MUST be specified if applicable.

Add support for evaluating rules for nested properties

Hello and thanks for creating this tool! We have openapilint in our nightly builds for all of the swagger files for our api endpoints.
We have requirements where it is necessary to evaluate nested properties within some of our rules. Some examples from our rules:
(rule - License object must contain a specific name value)

"info-custom": [
       {
        "whenField": "license",
        "whenPattern": ".*",
        "thenField": "license.name",
        "thenPattern": "^License: Creative Commons Attribution 4.0 International Public License$" 
        }
],

(rule -Non-empty responses must be of type object so they can easily be added to in the future)

"responses-custom": [
       {
        "whenField": "schema.type",
        "whenPattern": "^((?!undefined).)*$",
        "thenField": "schema.type",
        "thenPattern": "^object$"
        }
]

In our local version of openapilint I updated CustomValidator.js to accommodate references to nested properties in the rules. I can offer that change for review or open to other solutions to the requirement that might not require code changes.

DocsPath rule should be modified to allow periods.

DocPath rule should be modified to allow periods.

Expected or desired behavior:

DocPath rule should be modified to allow periods.
payments.billingAgreements => ok

Actual behavior:

payments.billingAgreements => bad

Steps to reproduce:

try payments.billingAgreements

[Rule] Do not allow logically equivalent paths

A path that differs only in its path template parameters should not be allowed.

Example of equivalent paths:
/pets/{pet_id}
/pets/{rascal_id}

Enhance dereferencing of parameter types

Hello,
We have been using the linter tool for a while now and actually encountered some of these $ref following gaps. I made some enhancements in particular to parameter referencing. This is a similar to another open issue. Parameters seem to be defined in one of 2 forms:

inline simple property:

'/wild-animals':
post:
parameters:

• name: 'PayPal-Request-Id',
  in: 'header',
  type: 'string',
  description: 'The server stores keys forever.',
  required: false

Or as a reference:
'/pets':
post:
parameters:

• $ref: '#/definitions/headerRef'

definitions:
headerRef:
name: 'PayPal-Request-Id',
in: 'header',
description: 'The server stores keys for 24 hours',
required: false,
type: 'string'

I added logic to SchemaObjectParser.js to differentiate these two use cases. In particular the simple form is detected by looking for the "in" property which is required for the parameter object.
Additionally, we use custom definition paths for some of our referenceable objects so that they get categorized. This resulted in changes to SchemaObjectParser.js to follow references using a more generic pattern.
These changes allowed the parameter-custom.js to look almost identical to properties-custom.js as there was no longer need to have special logic to look for parameters in the rules themselves. Similarly, TextParser.js no longer needs to do parameter checks as that is solely accomplished in SchemaObjectParser.js.
I updated the test suite to cover the multiple parameter forms and they run successfully, however, all these changes should have a review by others before committing.

[Rule] No additional fields on $refs

Some projects decide to support overriding a $ref's value. This isn't supported in OpenAPI, as mentioned in OAI/OpenAPI-Specification#556.

This rule would report an error for any properties specified in the same object as a valid $ref, except those allowed by the configuration.

Example:
If description were the only field allowed to be present here, the type and abc fields would be reported an error.

{
  "abc": "abc string",
  "description": "A description override.",
  "type": "object",
  "$ref": "#/definitions/referenced_definition"
}

[Rule] operation object should have a 'summary'

For some reason summary is optional in the swagger spec. This rule restricts it to mandatory.

[Rule] Ensure no duplicated properties

An object should not have duplicate properties, especially across allOf inclusions.

Clarify what version(s) of OpenAPI are supported

Current status?

Great stuff! Seems to be just what we're looking for.

I'm just wondering about what the dev status is, specifically for OpenAPI 3.0?