@redocly/openapi-core 1.0.0-beta.100

package/src/rules/oas3/__tests__/spec/spec.test.ts

@@ -0,0 +1,288 @@
+import { outdent } from 'outdent';
+import { lintDocument } from '../../../../lint';
+import { parseYamlToDocument, replaceSourceWithRef } from '../../../../../__tests__/utils';
+import { LintConfig, defaultPlugin, resolvePlugins, resolvePreset } from '../../../../config';
+
+import { BaseResolver } from '../../../../resolve';
+
+const plugins = resolvePlugins([defaultPlugin]);
+const pressets = resolvePreset('all', plugins);
+const allConfig = new LintConfig({ ...pressets, plugins });
+describe('Oas3 Structural visitor basic', () => {
+  it('should report wrong types', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.0.0
+          tags:
+            - 25.3
+            - test
+          servers:
+          - url: 'http://example.com'
+            variables:
+              a:
+                default: test
+                enum:
+                  - 123
+                  - test
+          info:
+            title: Test
+            version: '1.0'
+            description: test description
+            contact:
+              name: string
+              url: []
+              email: false
+            license: invalid
+          paths: {}
+        `,
+      'foobar.yaml',
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: allConfig,
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/info/contact/url",
+              "reportOnKey": false,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Expected type \`string\` but got \`array\`.",
+          "ruleId": "spec",
+          "severity": "error",
+          "suggest": Array [],
+        },
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/info/contact/email",
+              "reportOnKey": false,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Expected type \`string\` but got \`boolean\`.",
+          "ruleId": "spec",
+          "severity": "error",
+          "suggest": Array [],
+        },
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/info/license",
+              "reportOnKey": false,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Expected type \`License\` (object) but got \`string\`",
+          "ruleId": "spec",
+          "severity": "error",
+          "suggest": Array [],
+        },
+        Object {
+          "from": Object {
+            "pointer": "#/servers/0/url",
+            "source": "foobar.yaml",
+          },
+          "location": Array [
+            Object {
+              "pointer": "#/servers/0/variables/a",
+              "reportOnKey": true,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "The \`a\` variable is not used in the server's \`url\` field.",
+          "ruleId": "no-undefined-server-variable",
+          "severity": "error",
+          "suggest": Array [],
+        },
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/servers/0/variables/a/enum/0",
+              "reportOnKey": false,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Expected type \`string\` but got \`number\`.",
+          "ruleId": "spec",
+          "severity": "error",
+          "suggest": Array [],
+        },
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/tags/0",
+              "reportOnKey": false,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Expected type \`Tag\` (object) but got \`number\`",
+          "ruleId": "spec",
+          "severity": "error",
+          "suggest": Array [],
+        },
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/tags/1",
+              "reportOnKey": false,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Expected type \`Tag\` (object) but got \`string\`",
+          "ruleId": "spec",
+          "severity": "error",
+          "suggest": Array [],
+        },
+      ]
+    `);
+  });
+
+  it('should report unexpected properties', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.0.0
+          components1: 1
+          info:
+            title: Test
+            version: '1.0'
+            description: test description
+            license:
+              name: MIT
+              url: google.com
+            contact:
+              name: string
+              test: blah
+              x-test: vendor
+          paths: {}
+        `,
+      'foobar.yaml',
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: allConfig,
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/components1",
+              "reportOnKey": true,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Property \`components1\` is not expected here.",
+          "ruleId": "spec",
+          "severity": "error",
+          "suggest": Array [
+            "components",
+          ],
+        },
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/openapi",
+              "reportOnKey": true,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Servers must be present.",
+          "ruleId": "no-empty-servers",
+          "severity": "error",
+          "suggest": Array [],
+        },
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/info/contact/test",
+              "reportOnKey": true,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Property \`test\` is not expected here.",
+          "ruleId": "spec",
+          "severity": "error",
+          "suggest": Array [],
+        },
+      ]
+    `);
+  });
+
+  it('should report required properties missing', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.0.0
+          info:
+            version: '1.0'
+            description: test description
+            license:
+              name: MIT
+              url: google.com
+            contact:
+              name: string
+        `,
+      'foobar.yaml',
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: allConfig,
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/",
+              "reportOnKey": true,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "The field \`paths\` must be present on this level.",
+          "ruleId": "spec",
+          "severity": "error",
+          "suggest": Array [],
+        },
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/openapi",
+              "reportOnKey": true,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Servers must be present.",
+          "ruleId": "no-empty-servers",
+          "severity": "error",
+          "suggest": Array [],
+        },
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/info",
+              "reportOnKey": true,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "The field \`title\` must be present on this level.",
+          "ruleId": "spec",
+          "severity": "error",
+          "suggest": Array [],
+        },
+      ]
+    `);
+  });
+});

package/src/rules/oas3/__tests__/spec/utils.ts

@@ -0,0 +1,32 @@
+import { LintConfig, RuleConfig, resolveLint } from '../../../../config';
+import { parseYamlToDocument } from '../../../../../__tests__/utils';
+import { lintDocument } from '../../../../lint';
+import { BaseResolver } from '../../../../resolve';
+
+export async function validateDoc(
+  source: string,
+  rules: Record<string, RuleConfig> = { spec: 'error' },
+) {
+  const document = parseYamlToDocument(source, 'foobar.yaml');
+
+  const results = await lintDocument({
+    externalRefResolver: new BaseResolver(),
+    document,
+    config: new LintConfig(
+      await resolveLint({
+        lintConfig: {
+          plugins: [],
+          extends: [],
+          rules,
+        },
+      }),
+    ),
+  });
+
+  return results.map((res) => {
+    return {
+      message: res.message,
+      location: res.location[0].pointer || '',
+    };
+  });
+}

package/src/rules/oas3/boolean-parameter-prefixes.ts

@@ -0,0 +1,28 @@
+import { Oas3Rule } from '../../visitors';
+
+export type BooleanParameterPrefixesOptions = {
+  prefixes?: string[];
+};
+
+export const BooleanParameterPrefixes: Oas3Rule = (options: BooleanParameterPrefixesOptions) => {
+  const prefixes = options.prefixes || ['is', 'has'];
+  const regexp = new RegExp(`^(${prefixes.join('|')})[A-Z-_]`);
+  const wrappedPrefixes = prefixes.map((p) => `\`${p}\``);
+  const prefixesString =
+    wrappedPrefixes.length === 1
+      ? wrappedPrefixes[0]
+      : wrappedPrefixes.slice(0, -1).join(', ') + ' or ' + wrappedPrefixes[prefixes.length - 1];
+
+  return {
+    Parameter: {
+      Schema(schema, { report, parentLocations }, parents) {
+        if (schema.type === 'boolean' && !regexp.test(parents.Parameter.name)) {
+          report({
+            message: `Boolean parameter \`${parents.Parameter.name}\` should have ${prefixesString} prefix.`,
+            location: parentLocations.Parameter.child(['name']),
+          });
+        }
+      },
+    },
+  };
+};

package/src/rules/oas3/index.ts

@@ -0,0 +1,105 @@
+import { Oas3RuleSet } from '../../oas-types';
+import { OasSpec } from '../common/spec';
+import { Operation2xxResponse } from '../common/operation-2xx-response';
+import { Operation4xxResponse } from '../common/operation-4xx-response';
+import { Assertions } from '../common/assertions';
+import { OperationIdUnique } from '../common/operation-operationId-unique';
+import { OperationParametersUnique } from '../common/operation-parameters-unique';
+import { PathParamsDefined } from '../common/path-params-defined';
+import { OperationTagDefined } from '../common/operation-tag-defined';
+import { NoExampleValueAndExternalValue } from './no-example-value-and-externalValue';
+import { NoEnumTypeMismatch } from '../common/no-enum-type-mismatch';
+import { NoPathTrailingSlash } from '../common/no-path-trailing-slash';
+import { PathDeclarationMustExist } from '../common/path-declaration-must-exist';
+import { OperationIdUrlSafe } from '../common/operation-operationId-url-safe';
+import { TagsAlphabetical } from '../common/tags-alphabetical';
+import { NoServerExample } from './no-server-example.com';
+import { NoServerTrailingSlash } from './no-server-trailing-slash';
+import { InfoDescription } from '../common/info-description';
+import { TagDescription } from '../common/tag-description';
+import { InfoContact } from '../common/info-contact';
+import { InfoLicense } from '../common/info-license-url';
+import { OperationDescription } from '../common/operation-description';
+import { NoUnusedComponents } from './no-unused-components';
+import { PathNotIncludeQuery } from '../common/path-not-include-query';
+import { ParameterDescription } from '../common/parameter-description';
+import { OperationSingularTag } from '../common/operation-singular-tag';
+import { InfoLicenseUrl } from '../common/license-url';
+import { OperationSecurityDefined } from '../common/operation-security-defined';
+import { NoUnresolvedRefs } from '../no-unresolved-refs';
+import { BooleanParameterPrefixes } from './boolean-parameter-prefixes';
+import { PathsKebabCase } from '../common/paths-kebab-case';
+import { PathHttpVerbsOrder } from '../common/path-http-verbs-order';
+import { NoEmptyServers } from './no-empty-servers';
+import { ValidContentExamples } from './no-invalid-media-type-examples';
+import { NoIdenticalPaths } from '../common/no-identical-paths';
+import { NoUndefinedServerVariable } from './no-undefined-server-variable';
+import { OperationOperationId } from '../common/operation-operationId';
+import { OperationSummary } from '../common/operation-summary';
+import { NoAmbiguousPaths } from '../common/no-ambiguous-paths';
+import { NoEmptyEnumServers } from './no-servers-empty-enum';
+import { NoHttpVerbsInPaths } from '../common/no-http-verbs-in-paths';
+import { RequestMimeType } from './request-mime-type';
+import { ResponseMimeType } from './response-mime-type';
+import { PathSegmentPlural } from '../common/path-segment-plural';
+import { PathExcludesPatterns } from '../common/path-excludes-patterns';
+import { NoInvalidSchemaExamples } from '../common/no-invalid-schema-examples';
+import { NoInvalidParameterExamples } from '../common/no-invalid-parameter-examples';
+import { ResponseContainsHeader } from '../common/response-contains-header';
+import { ResponseContainsProperty } from './response-contains-property';
+import { ScalarPropertyMissingExample } from '../common/scalar-property-missing-example';
+
+export const rules = {
+  spec: OasSpec,
+  'info-description': InfoDescription,
+  'info-contact': InfoContact,
+  'info-license': InfoLicense,
+  'info-license-url': InfoLicenseUrl,
+  'operation-2xx-response': Operation2xxResponse,
+  'operation-4xx-response': Operation4xxResponse,
+  'assertions': Assertions,
+  'operation-operationId-unique': OperationIdUnique,
+  'operation-parameters-unique': OperationParametersUnique,
+  'path-parameters-defined': PathParamsDefined,
+  'operation-tag-defined': OperationTagDefined,
+  'no-example-value-and-externalValue': NoExampleValueAndExternalValue,
+  'no-enum-type-mismatch': NoEnumTypeMismatch,
+  'no-path-trailing-slash': NoPathTrailingSlash,
+  'no-empty-servers': NoEmptyServers,
+  'path-declaration-must-exist': PathDeclarationMustExist,
+  'operation-operationId-url-safe': OperationIdUrlSafe,
+  'operation-operationId': OperationOperationId,
+  'operation-summary': OperationSummary,
+  'tags-alphabetical': TagsAlphabetical,
+  'no-server-example.com': NoServerExample,
+  'no-server-trailing-slash': NoServerTrailingSlash,
+  'tag-description': TagDescription,
+  'operation-description': OperationDescription,
+  'no-unused-components': NoUnusedComponents,
+  'path-not-include-query': PathNotIncludeQuery,
+  'path-params-defined': PathParamsDefined,
+  'parameter-description': ParameterDescription,
+  'operation-singular-tag': OperationSingularTag,
+  'operation-security-defined': OperationSecurityDefined,
+  'no-unresolved-refs': NoUnresolvedRefs,
+  'paths-kebab-case': PathsKebabCase,
+  'boolean-parameter-prefixes': BooleanParameterPrefixes,
+  'path-http-verbs-order': PathHttpVerbsOrder,
+  'no-invalid-media-type-examples': ValidContentExamples,
+  'no-identical-paths': NoIdenticalPaths,
+  'no-ambiguous-paths': NoAmbiguousPaths,
+  'no-undefined-server-variable': NoUndefinedServerVariable,
+  'no-servers-empty-enum': NoEmptyEnumServers,
+  'no-http-verbs-in-paths': NoHttpVerbsInPaths,
+  'path-excludes-patterns': PathExcludesPatterns,
+  'request-mime-type': RequestMimeType,
+  'response-mime-type': ResponseMimeType,
+  'path-segment-plural': PathSegmentPlural,
+  'no-invalid-schema-examples': NoInvalidSchemaExamples,
+  'no-invalid-parameter-examples': NoInvalidParameterExamples,
+  'response-contains-header': ResponseContainsHeader,
+  'response-contains-property': ResponseContainsProperty,
+  'scalar-property-missing-example': ScalarPropertyMissingExample,
+} as Oas3RuleSet;
+
+export const preprocessors = {};

package/src/rules/oas3/no-empty-servers.ts

@@ -0,0 +1,22 @@
+import { Oas3Rule } from '../../visitors';
+
+export const NoEmptyServers: Oas3Rule = () => {
+  return {
+    DefinitionRoot(root, { report, location }) {
+      if (!root.hasOwnProperty('servers')) {
+        report({
+          message: 'Servers must be present.',
+          location: location.child(['openapi']).key()
+        });
+        return;
+      }
+
+      if (!Array.isArray(root.servers) || root.servers.length === 0) {
+        report({
+          message: 'Servers must be a non-empty array.',
+          location: location.child(['servers']).key(),
+        });
+      }
+    },
+  };
+};

package/src/rules/oas3/no-example-value-and-externalValue.ts

@@ -0,0 +1,14 @@
+import { Oas3Rule } from '../../visitors';
+
+export const NoExampleValueAndExternalValue: Oas3Rule = () => {
+  return {
+    Example(example, { report, location }) {
+      if (example.value && example.externalValue) {
+        report({
+          message: 'Example object can have either `value` or `externalValue` fields.',
+          location: location.child(['value']).key(),
+        });
+      }
+    },
+  };
+};

package/src/rules/oas3/no-invalid-media-type-examples.ts

@@ -0,0 +1,41 @@
+import { Oas3Rule } from '../../visitors';
+import { Location, isRef } from '../../ref-utils';
+import { Oas3Example } from '../../typings/openapi';
+import { validateExample } from '../utils';
+import { UserContext } from '../../walk';
+
+export const ValidContentExamples: Oas3Rule = (opts) => {
+  const disallowAdditionalProperties = opts.disallowAdditionalProperties ?? true;
+
+  return {
+    MediaType: {
+      leave(mediaType, ctx: UserContext) {
+        const { location, resolve } = ctx;
+        if (!mediaType.schema) return;
+        if (mediaType.example) {
+         resolveAndValidateExample(mediaType.example, location.child('example'));
+        } else if (mediaType.examples) {
+          for (const exampleName of Object.keys(mediaType.examples)) {
+            resolveAndValidateExample(mediaType.examples[exampleName], location.child(['examples', exampleName, 'value']), true);
+          }
+        }
+
+        function resolveAndValidateExample(example: Oas3Example | any, location: Location, isMultiple?: boolean) {
+          if (isRef(example)) {
+            const resolved = resolve<Oas3Example>(example);
+            if (!resolved.location) return;
+            location = isMultiple ? resolved.location.child('value') : resolved.location;
+            example = resolved.node;
+          }
+          validateExample(
+            isMultiple ? example.value : example,
+            mediaType.schema!,
+            location,
+            ctx,
+            disallowAdditionalProperties,
+          );
+        }
+      },
+    },
+  };
+};

package/src/rules/oas3/no-server-example.com.ts

@@ -0,0 +1,14 @@
+import { Oas3Rule } from '../../visitors';
+
+export const NoServerExample: Oas3Rule = () => {
+  return {
+    Server(server, { report, location }) {
+      if (['example.com', 'localhost'].indexOf(server.url) !== -1) {
+        report({
+          message: 'Server `url` should not point at example.com.',
+          location: location.child(['url']),
+        });
+      }
+    },
+  };
+};

package/src/rules/oas3/no-server-trailing-slash.ts

@@ -0,0 +1,15 @@
+import { Oas3Rule } from '../../visitors';
+
+export const NoServerTrailingSlash: Oas3Rule = () => {
+  return {
+    Server(server, { report, location }) {
+      if (!server.url) return;
+      if (server.url.endsWith('/') && server.url !== '/') {
+        report({
+          message: 'Server `url` should not have a trailing slash.',
+          location: location.child(['url']),
+        });
+      }
+    },
+  };
+};

package/src/rules/oas3/no-servers-empty-enum.ts

@@ -0,0 +1,67 @@
+import { Oas3Server } from 'core/src/typings/openapi';
+import { Oas3Rule } from '../../visitors';
+
+enum enumError {
+  empty = 'empty',
+  invalidDefaultValue = 'invalidDefaultValue',
+}
+
+export const NoEmptyEnumServers: Oas3Rule = () => {
+  return {
+    DefinitionRoot(root, { report, location }) {
+      if (!root.servers || root.servers.length === 0) return;
+
+      const invalidVariables: enumError[] = [];
+
+      if (Array.isArray(root.servers)) {
+        for (const server of root.servers) {
+          const enumErrors = checkEnumVariables(server);
+          if (!enumErrors) continue;
+          invalidVariables.push(...enumErrors);
+        }
+      } else {
+        const enumErrors = checkEnumVariables(root.servers);
+        if (!enumErrors) return;
+        invalidVariables.push(...enumErrors);
+      }
+
+      for(const invalidVariable of invalidVariables) {
+        if(invalidVariable === enumError.empty) {
+          report({
+            message: 'Server variable with `enum` must be a non-empty array.',
+            location: location.child(['servers']).key(),
+          });
+        }
+        if(invalidVariable === enumError.invalidDefaultValue) {
+          report({
+            message: 'Server variable define `enum` and `default`. `enum` must include default value',
+            location: location.child(['servers']).key(),
+          });
+        }
+      }
+    },
+  };
+};
+
+function checkEnumVariables(server: Oas3Server): enumError[] | undefined{
+  if (server.variables && Object.keys(server.variables).length === 0)
+    return;
+
+  const errors: enumError[] = [];
+  for(var variable in server.variables) {
+    const serverVariable = server.variables[variable];
+    if (!serverVariable.enum) continue;
+
+    if (Array.isArray(serverVariable.enum) && serverVariable.enum?.length === 0)
+      errors.push(enumError.empty);
+
+    if (!serverVariable.default)
+      continue;
+
+    const defaultValue = server.variables[variable].default;
+    if (serverVariable.enum && !serverVariable.enum.includes(defaultValue))
+      errors.push(enumError.invalidDefaultValue);
+  }
+  if (errors.length) return errors;
+  return;
+}

package/src/rules/oas3/no-undefined-server-variable.ts

@@ -0,0 +1,30 @@
+import { Oas3Rule } from '../../visitors';
+
+export const NoUndefinedServerVariable: Oas3Rule = () => {
+  return {
+    Server(server, { report, location }) {
+      if (!server.url) return;
+      const urlVariables = server.url.match(/{[^}]+}/g)?.map((e) => e.slice(1, e.length - 1)) || [];
+      const definedVariables = (server?.variables && Object.keys(server.variables)) || [];
+
+      for (const serverVar of urlVariables) {
+        if (!definedVariables.includes(serverVar)) {
+          report({
+            message: `The \`${serverVar}\` variable is not defined in the \`variables\` objects.`,
+            location: location.child(['url']),
+          });
+        }
+      }
+
+      for (const definedServerVar of definedVariables) {
+        if (!urlVariables.includes(definedServerVar)) {
+          report({
+            message: `The \`${definedServerVar}\` variable is not used in the server's \`url\` field.`,
+            location: location.child(['variables', definedServerVar]).key(),
+            from: location.child('url'),
+          });
+        }
+      }
+    },
+  };
+};