Types extension

[knidarkness]

This PR introduces a concept of extending and redefining types and rules.

Description

From this version, user can add custom fields into default objects in all levels, which will then validate using either existing validators (for existing types, either with custom rules, created by user).

To extend or define a type, user should create a file and pass it as a typeExtension parameter in the config. It should follow such pattern (quite similar to usual reducers):

module.exports = (types) => ({
  ...types,
  OpenAPIParameter: {
    ...types.OpenAPIParameter,
    resolveType: (node) => (node.allOf ? 'OpenAPIParameterWithAllOf' : 'OpenAPIParameter'),
  },
  OpenAPIParameterWithAllOf: {
    name: 'OpenAPIParameterWithAllOf',
    properties: {
      allOf: 'OpenAPIParameterPartial',
    },
  },
  OpenAPIParameterPartial: {
    ...types.OpenAPIParameter,
    name: 'OpenAPIParameterPartial',
  },
});

Here, user adds field allOf to Parameter type.

null value in the properties object is allowed and means that given property is a leaf in the type-tree.

To extend ruleset user can create another file and set it as customRules param of config with such contents:

class ValidateOpenAPIParameterPartial {
  static get rule() {
    return 'parameterPartial';
  }

  OpenAPIParameterPartial() {
    return {
      onEnter: (node, definition, ctx) => {
        const result = [];
        let validators = {};
        if (Object.keys(node).length === 1 && node.description) {
          validators = {
            description: ctx.getRule('oas3-schema/parameter').validators.description,
          };
        } else {
          validators = {
            ...ctx.getRule('oas3-schema/parameter').validators,
          };
        }
        if (node.in && node.in !== 'header') { // just as an example
          ctx.path.push('in');
          result.push(ctx.createError('Only header parameters can be extended with allOf', 'key'));
          ctx.path.pop();
        }
        const fieldMessages = ctx.validateFieldsHelper(validators);
        result.push(...fieldMessages);
        return result;
      },
    };
  }
}
class Other {
  static get rule() {
    return 'parameterWithAllOf';
  }

  OpenAPIParameterWithAllOf() {
    return {
      onEnter: (node, definition, ctx) => {
        const result = [];
        if (node.allOf.length > 2) {
          ctx.path.push('allOf');
          result.push(ctx.createError('Do not use more that 2 items in allOf for OpenAPI Parameter', 'key' /* whaterver else */));
          ctx.path.pop();
        }
        return result;
      },
    };
  }
}
module.exports = [
  ValidateOpenAPIParameterPartial, Other,
];

User should provide configuration file .openapi-cli.yaml in the root of the definition directory.

typeExtension: typeExtension.js # relative path to the extended types
customRules: customRules.js # relative path to the custom visitors
rules:
  parameterPartial: warning # allowed values are 'error', 'warning' and 'off'
  parameterWithAllOf: off # by default custom rules are 'on' and set to 'error' severity

[RomanHotsiy]

Added a few comments

[RomanHotsiy]

I think you can assign the value directly on this line

[knidarkness]

agree

[RomanHotsiy]

Do we need every custom rule to add this code? Maybe we can provide some base class with this behaviour handled. Also, where is this level used later? Is it propagated down the visitor invocations?

Also, I thing we should export constants for those 1, 2, 3, 4 numbers :)

[knidarkness]

I wanted to make custom rules completely 0-dependency. We can just inherit from AbstractVisitor class and don't do this manually

[knidarkness]

Also, numbers are in constants elsewhere

[RomanHotsiy]

Hmm. I think 0-dep makes sense. Maybe, instead we can just keep string values and adjust other related code to accept them instead of/ additionally to number values?

[knidarkness]

Hmmm, yes, that might work fine

[RomanHotsiy]

how to add an error from this validator? Could you add an example of validating the description field to be a string (using some custom code)

[knidarkness]

for now we allow types (re)definition, not so much custom validators. we can (not sure if already) load additional rules (with are the same syntax/structure) as our own ones and run them on types we want