@redocly/openapi-core 1.0.0 → 1.0.2

package/src/rules/oas3/component-name-unique.ts

@@ -0,0 +1,158 @@
+import { Problem, UserContext } from '../../walk';
+import { Oas2Rule, Oas3Rule, Oas3Visitor } from '../../visitors';
+import {
+  Oas3Definition,
+  Oas3Parameter,
+  Oas3RequestBody,
+  Oas3Response,
+  Oas3Schema,
+  OasRef,
+} from '../../typings/openapi';
+
+const TYPE_NAME_SCHEMA = 'Schema';
+const TYPE_NAME_PARAMETER = 'Parameter';
+const TYPE_NAME_RESPONSE = 'Response';
+const TYPE_NAME_REQUEST_BODY = 'RequestBody';
+
+const TYPE_NAME_TO_OPTION_COMPONENT_NAME: { [key: string]: string } = {
+  [TYPE_NAME_SCHEMA]: 'schemas',
+  [TYPE_NAME_PARAMETER]: 'parameters',
+  [TYPE_NAME_RESPONSE]: 'responses',
+  [TYPE_NAME_REQUEST_BODY]: 'requestBodies',
+};
+
+export const ComponentNameUnique: Oas3Rule | Oas2Rule = (options) => {
+  const components = new Map<string, Set<string>>();
+
+  const typeNames: string[] = [];
+  if (options.schemas !== 'off') {
+    typeNames.push(TYPE_NAME_SCHEMA);
+  }
+  if (options.parameters !== 'off') {
+    typeNames.push(TYPE_NAME_PARAMETER);
+  }
+  if (options.responses !== 'off') {
+    typeNames.push(TYPE_NAME_RESPONSE);
+  }
+  if (options.requestBodies !== 'off') {
+    typeNames.push(TYPE_NAME_REQUEST_BODY);
+  }
+
+  const rule: Oas3Visitor = {
+    ref: {
+      leave(ref: OasRef, { type, resolve }: UserContext) {
+        const typeName = type.name;
+        if (typeNames.includes(typeName)) {
+          const resolvedRef = resolve(ref);
+          if (!resolvedRef.location) return;
+
+          addComponentFromAbsoluteLocation(
+            typeName,
+            resolvedRef.location.absolutePointer.toString()
+          );
+        }
+      },
+    },
+    Root: {
+      leave(root: Oas3Definition, ctx: UserContext) {
+        components.forEach((value, key, _) => {
+          if (value.size > 1) {
+            const component = getComponentFromKey(key);
+            const optionComponentName = getOptionComponentNameForTypeName(component.typeName);
+            const definitions = Array.from(value)
+              .map((v) => `- ${v}`)
+              .join('\n');
+
+            const problem: Problem = {
+              message: `Component '${optionComponentName}/${component.componentName}' is not unique. It is defined at:\n${definitions}`,
+            };
+
+            const componentSeverity = optionComponentName ? options[optionComponentName] : null;
+            if (componentSeverity) {
+              problem.forceSeverity = componentSeverity;
+            }
+            ctx.report(problem);
+          }
+        });
+      },
+    },
+  };
+
+  if (options.schemas != 'off') {
+    rule.NamedSchemas = {
+      Schema(_: Oas3Schema, { location }: UserContext) {
+        addComponentFromAbsoluteLocation(TYPE_NAME_SCHEMA, location.absolutePointer.toString());
+      },
+    };
+  }
+
+  if (options.responses != 'off') {
+    rule.NamedResponses = {
+      Response(_: Oas3Response, { location }: UserContext) {
+        addComponentFromAbsoluteLocation(TYPE_NAME_RESPONSE, location.absolutePointer.toString());
+      },
+    };
+  }
+
+  if (options.parameters != 'off') {
+    rule.NamedParameters = {
+      Parameter(_: Oas3Parameter, { location }: UserContext) {
+        addComponentFromAbsoluteLocation(TYPE_NAME_PARAMETER, location.absolutePointer.toString());
+      },
+    };
+  }
+
+  if (options.requestBodies != 'off') {
+    rule.NamedRequestBodies = {
+      RequestBody(_: Oas3RequestBody, { location }: UserContext) {
+        addComponentFromAbsoluteLocation(
+          TYPE_NAME_REQUEST_BODY,
+          location.absolutePointer.toString()
+        );
+      },
+    };
+  }
+
+  return rule;
+
+  function getComponentNameFromAbsoluteLocation(absoluteLocation: string): string {
+    const componentName = absoluteLocation.split('/').slice(-1)[0];
+    if (
+      componentName.endsWith('.yml') ||
+      componentName.endsWith('.yaml') ||
+      componentName.endsWith('.json')
+    ) {
+      return componentName.slice(0, componentName.lastIndexOf('.'));
+    }
+    return componentName;
+  }
+
+  function addFoundComponent(
+    typeName: string,
+    componentName: string,
+    absoluteLocation: string
+  ): void {
+    const key = getKeyForComponent(typeName, componentName);
+    const locations = components.get(key) ?? new Set();
+    locations.add(absoluteLocation);
+    components.set(key, locations);
+  }
+
+  function addComponentFromAbsoluteLocation(typeName: string, absoluteLocation: string): void {
+    const componentName = getComponentNameFromAbsoluteLocation(absoluteLocation);
+    addFoundComponent(typeName, componentName, absoluteLocation);
+  }
+};
+
+function getOptionComponentNameForTypeName(typeName: string): string | null {
+  return TYPE_NAME_TO_OPTION_COMPONENT_NAME[typeName] ?? null;
+}
+
+function getKeyForComponent(typeName: string, componentName: string): string {
+  return `${typeName}/${componentName}`;
+}
+
+function getComponentFromKey(key: string): { typeName: string; componentName: string } {
+  const [typeName, componentName] = key.split('/');
+  return { typeName, componentName };
+}

package/src/rules/oas3/index.ts

@@ -0,0 +1,113 @@
+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 { TagDescription } from '../common/tag-description';
+import { InfoContact } from '../common/info-contact';
+import { InfoLicense } from '../common/info-license';
+import { InfoLicenseUrl } 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 { SecurityDefined } from '../common/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 { NoServerVariablesEmptyEnum } from './no-server-variables-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';
+import { SpecComponentsInvalidMapName } from './spec-components-invalid-map-name';
+import { Operation4xxProblemDetailsRfc7807 } from './operation-4xx-problem-details-rfc7807';
+import { RequiredStringPropertyMissingMinLength } from '../common/required-string-property-missing-min-length';
+import { SpecStrictRefs } from '../common/spec-strict-refs';
+import { ComponentNameUnique } from './component-name-unique';
+
+export const rules = {
+  spec: OasSpec,
+  'info-contact': InfoContact,
+  'info-license': InfoLicense,
+  'info-license-url': InfoLicenseUrl,
+  'operation-2xx-response': Operation2xxResponse,
+  'operation-4xx-response': Operation4xxResponse,
+  'operation-4xx-problem-details-rfc7807': Operation4xxProblemDetailsRfc7807,
+  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,
+  'security-defined': SecurityDefined,
+  '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-server-variables-empty-enum': NoServerVariablesEmptyEnum,
+  '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,
+  'spec-components-invalid-map-name': SpecComponentsInvalidMapName,
+  'required-string-property-missing-min-length': RequiredStringPropertyMissingMinLength,
+  'spec-strict-refs': SpecStrictRefs,
+  'component-name-unique': ComponentNameUnique,
+} 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 {
+    Root(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,49 @@
+import { Oas3Rule } from '../../visitors';
+import { Location, isRef } from '../../ref-utils';
+import { Oas3Example } from '../../typings/openapi';
+import { getAdditionalPropertiesOption, validateExample } from '../utils';
+import { UserContext } from '../../walk';
+
+export const ValidContentExamples: Oas3Rule = (opts) => {
+  const allowAdditionalProperties = getAdditionalPropertiesOption(opts) ?? false;
+
+  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,
+            allowAdditionalProperties
+          );
+        }
+      },
+    },
+  };
+};

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-server-variables-empty-enum.ts

@@ -0,0 +1,66 @@
+import { Oas3Server } from 'core/src/typings/openapi';
+import { Oas3Rule } from '../../visitors';
+
+enum enumError {
+  empty = 'empty',
+  invalidDefaultValue = 'invalidDefaultValue',
+}
+
+export const NoServerVariablesEmptyEnum: Oas3Rule = () => {
+  return {
+    Root(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 (const 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'),
+          });
+        }
+      }
+    },
+  };
+};

package/src/rules/oas3/no-unused-components.ts

@@ -0,0 +1,75 @@
+import { Oas3Rule } from '../../visitors';
+import { Location } from '../../ref-utils';
+
+export const NoUnusedComponents: Oas3Rule = () => {
+  const components = new Map<string, { used: boolean; location: Location; name: string }>();
+
+  function registerComponent(location: Location, name: string): void {
+    components.set(location.absolutePointer, {
+      used: components.get(location.absolutePointer)?.used || false,
+      location,
+      name,
+    });
+  }
+
+  return {
+    ref(ref, { type, resolve, key, location }) {
+      if (
+        ['Schema', 'Header', 'Parameter', 'Response', 'Example', 'RequestBody'].includes(type.name)
+      ) {
+        const resolvedRef = resolve(ref);
+        if (!resolvedRef.location) return;
+        components.set(resolvedRef.location.absolutePointer, {
+          used: true,
+          name: key.toString(),
+          location,
+        });
+      }
+    },
+    Root: {
+      leave(_, { report }) {
+        components.forEach((usageInfo) => {
+          if (!usageInfo.used) {
+            report({
+              message: `Component: "${usageInfo.name}" is never used.`,
+              location: usageInfo.location.key(),
+            });
+          }
+        });
+      },
+    },
+    NamedSchemas: {
+      Schema(schema, { location, key }) {
+        if (!schema.allOf) {
+          // FIXME: find a better way to detect possible discriminator
+          registerComponent(location, key.toString());
+        }
+      },
+    },
+    NamedParameters: {
+      Parameter(_parameter, { location, key }) {
+        registerComponent(location, key.toString());
+      },
+    },
+    NamedResponses: {
+      Response(_response, { location, key }) {
+        registerComponent(location, key.toString());
+      },
+    },
+    NamedExamples: {
+      Example(_example, { location, key }) {
+        registerComponent(location, key.toString());
+      },
+    },
+    NamedRequestBodies: {
+      RequestBody(_requestBody, { location, key }) {
+        registerComponent(location, key.toString());
+      },
+    },
+    NamedHeaders: {
+      Header(_header, { location, key }) {
+        registerComponent(location, key.toString());
+      },
+    },
+  };
+};

package/src/rules/oas3/operation-4xx-problem-details-rfc7807.ts

@@ -0,0 +1,35 @@
+import type { Oas3Rule } from '../../visitors';
+import type { UserContext } from '../../walk';
+import { validateDefinedAndNonEmpty } from '../utils';
+
+/**
+ * Validation according to rfc7807 - https://datatracker.ietf.org/doc/html/rfc7807
+ */
+export const Operation4xxProblemDetailsRfc7807: Oas3Rule = () => {
+  return {
+    Response: {
+      skip(_, key: string | number) {
+        return !/4[Xx0-9]{2}/.test(`${key}`);
+      },
+      enter(response, { report, location }: UserContext) {
+        if (!response.content || !response.content['application/problem+json'])
+          report({
+            message: 'Response `4xx` must have content-type `application/problem+json`.',
+            location: location.key(),
+          });
+      },
+      MediaType: {
+        skip(_, key: string | number) {
+          return key !== 'application/problem+json';
+        },
+        enter(media, ctx: UserContext) {
+          validateDefinedAndNonEmpty('schema', media, ctx);
+        },
+        SchemaProperties(schema, ctx: UserContext) {
+          validateDefinedAndNonEmpty('type', schema, ctx);
+          validateDefinedAndNonEmpty('title', schema, ctx);
+        },
+      },
+    },
+  };
+};