@redocly/openapi-core 1.0.0 → 1.0.1

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

@@ -0,0 +1,95 @@
+import { Oas3Rule } from '../../visitors';
+import { Location } from '../../ref-utils';
+import { Oas3Components } from '../../typings/openapi';
+import { isEmptyObject } from '../../utils';
+
+export const RemoveUnusedComponents: Oas3Rule = () => {
+  const components = new Map<
+    string,
+    { used: boolean; componentType?: keyof Oas3Components; name: string }
+  >();
+
+  function registerComponent(
+    location: Location,
+    componentType: keyof Oas3Components,
+    name: string
+  ): void {
+    components.set(location.absolutePointer, {
+      used: components.get(location.absolutePointer)?.used || false,
+      componentType,
+      name,
+    });
+  }
+
+  return {
+    ref: {
+      leave(ref, { type, resolve, key }) {
+        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(),
+          });
+        }
+      },
+    },
+    Root: {
+      leave(root, ctx) {
+        const data = ctx.getVisitorData() as { removedCount: number };
+        data.removedCount = 0;
+
+        components.forEach((usageInfo) => {
+          const { used, componentType, name } = usageInfo;
+          if (!used && componentType && root.components) {
+            const componentChild = root.components[componentType];
+            delete componentChild![name];
+            data.removedCount++;
+            if (isEmptyObject(componentChild)) {
+              delete root.components[componentType];
+            }
+          }
+        });
+        if (isEmptyObject(root.components)) {
+          delete root.components;
+        }
+      },
+    },
+    NamedSchemas: {
+      Schema(schema, { location, key }) {
+        if (!schema.allOf) {
+          registerComponent(location, 'schemas', key.toString());
+        }
+      },
+    },
+    NamedParameters: {
+      Parameter(_parameter, { location, key }) {
+        registerComponent(location, 'parameters', key.toString());
+      },
+    },
+    NamedResponses: {
+      Response(_response, { location, key }) {
+        registerComponent(location, 'responses', key.toString());
+      },
+    },
+    NamedExamples: {
+      Example(_example, { location, key }) {
+        registerComponent(location, 'examples', key.toString());
+      },
+    },
+    NamedRequestBodies: {
+      RequestBody(_requestBody, { location, key }) {
+        registerComponent(location, 'requestBodies', key.toString());
+      },
+    },
+    NamedHeaders: {
+      Header(_header, { location, key }) {
+        registerComponent(location, 'headers', key.toString());
+      },
+    },
+  };
+};

package/src/rules/oas3/request-mime-type.ts

@@ -0,0 +1,30 @@
+import type { Oas3Rule } from '../../visitors';
+import type { UserContext } from '../../walk';
+import { validateMimeTypeOAS3 } from '../../utils';
+
+export const RequestMimeType: Oas3Rule = ({ allowedValues }) => {
+  return {
+    Paths: {
+      RequestBody: {
+        leave(requestBody, ctx: UserContext) {
+          validateMimeTypeOAS3({ type: 'consumes', value: requestBody }, ctx, allowedValues);
+        },
+      },
+      Callback: {
+        RequestBody() {},
+        Response: {
+          leave(response, ctx: UserContext) {
+            validateMimeTypeOAS3({ type: 'consumes', value: response }, ctx, allowedValues);
+          },
+        },
+      },
+    },
+    WebhooksMap: {
+      Response: {
+        leave(response, ctx: UserContext) {
+          validateMimeTypeOAS3({ type: 'consumes', value: response }, ctx, allowedValues);
+        },
+      },
+    },
+  };
+};

package/src/rules/oas3/response-contains-property.ts

@@ -0,0 +1,38 @@
+import { Oas3Rule } from '../../visitors';
+import { UserContext } from '../../walk';
+import { getMatchingStatusCodeRange } from '../../utils';
+
+export const ResponseContainsProperty: Oas3Rule = (options) => {
+  const names: Record<string, string[]> = options.names || {};
+  let key: string | number;
+  return {
+    Operation: {
+      Response: {
+        skip: (_response, key) => {
+          return `${key}` === '204';
+        },
+        enter: (_response, ctx: UserContext) => {
+          key = ctx.key;
+        },
+        MediaType: {
+          Schema(schema, { report, location }) {
+            if (schema.type !== 'object') return;
+            const expectedProperties =
+              names[key] ||
+              names[getMatchingStatusCodeRange(key)] ||
+              names[getMatchingStatusCodeRange(key).toLowerCase()] ||
+              [];
+            for (const expectedProperty of expectedProperties) {
+              if (!schema.properties?.[expectedProperty]) {
+                report({
+                  message: `Response object must contain a top-level "${expectedProperty}" property.`,
+                  location: location.child('properties').key(),
+                });
+              }
+            }
+          },
+        },
+      },
+    },
+  };
+};

package/src/rules/oas3/response-mime-type.ts

@@ -0,0 +1,30 @@
+import type { Oas3Rule } from '../../visitors';
+import type { UserContext } from '../../walk';
+import { validateMimeTypeOAS3 } from '../../utils';
+
+export const ResponseMimeType: Oas3Rule = ({ allowedValues }) => {
+  return {
+    Paths: {
+      Response: {
+        leave(response, ctx: UserContext) {
+          validateMimeTypeOAS3({ type: 'produces', value: response }, ctx, allowedValues);
+        },
+      },
+      Callback: {
+        Response() {},
+        RequestBody: {
+          leave(requestBody, ctx: UserContext) {
+            validateMimeTypeOAS3({ type: 'produces', value: requestBody }, ctx, allowedValues);
+          },
+        },
+      },
+    },
+    WebhooksMap: {
+      RequestBody: {
+        leave(requestBody, ctx: UserContext) {
+          validateMimeTypeOAS3({ type: 'produces', value: requestBody }, ctx, allowedValues);
+        },
+      },
+    },
+  };
+};

package/src/rules/oas3/spec-components-invalid-map-name.ts

@@ -0,0 +1,69 @@
+import { Oas3Rule } from '../../visitors';
+import { Problem, UserContext } from '../../walk';
+import { Location } from '../../ref-utils';
+
+export const SpecComponentsInvalidMapName: Oas3Rule = () => {
+  const KEYS_REGEX = '^[a-zA-Z0-9\\.\\-_]+$';
+
+  function validateKey(
+    key: string | number,
+    report: (problem: Problem) => void,
+    location: Location,
+    component: string
+  ) {
+    if (!new RegExp(KEYS_REGEX).test(key as string)) {
+      report({
+        message: `The map key in ${component} "${key}" does not match the regular expression "${KEYS_REGEX}"`,
+        location: location.key(),
+      });
+    }
+  }
+
+  return {
+    NamedSchemas: {
+      Schema(_node, { key, report, location }: UserContext) {
+        validateKey(key, report, location, 'schemas');
+      },
+    },
+    NamedParameters: {
+      Parameter(_node, { key, report, location }: UserContext) {
+        validateKey(key, report, location, 'parameters');
+      },
+    },
+    NamedResponses: {
+      Response(_node, { key, report, location }: UserContext) {
+        validateKey(key, report, location, 'responses');
+      },
+    },
+    NamedExamples: {
+      Example(_node, { key, report, location }: UserContext) {
+        validateKey(key, report, location, 'examples');
+      },
+    },
+    NamedRequestBodies: {
+      RequestBody(_node, { key, report, location }: UserContext) {
+        validateKey(key, report, location, 'requestBodies');
+      },
+    },
+    NamedHeaders: {
+      Header(_node, { key, report, location }: UserContext) {
+        validateKey(key, report, location, 'headers');
+      },
+    },
+    NamedSecuritySchemes: {
+      SecurityScheme(_node, { key, report, location }: UserContext) {
+        validateKey(key, report, location, 'securitySchemes');
+      },
+    },
+    NamedLinks: {
+      Link(_node, { key, report, location }: UserContext) {
+        validateKey(key, report, location, 'links');
+      },
+    },
+    NamedCallbacks: {
+      Callback(_node, { key, report, location }: UserContext) {
+        validateKey(key, report, location, 'callbacks');
+      },
+    },
+  };
+};

package/src/rules/other/stats.ts

@@ -0,0 +1,73 @@
+import { Oas3Parameter, OasRef, Oas3Tag } from '../../typings/openapi';
+import { Oas2Parameter } from '../../typings/swagger';
+import { StatsAccumulator } from '../../typings/common';
+
+export const Stats = (statsAccumulator: StatsAccumulator) => {
+  return {
+    ExternalDocs: {
+      leave() {
+        statsAccumulator.externalDocs.total++;
+      },
+    },
+    ref: {
+      enter(ref: OasRef) {
+        statsAccumulator.refs.items!.add(ref['$ref']);
+      },
+    },
+    Tag: {
+      leave(tag: Oas3Tag) {
+        statsAccumulator.tags.items!.add(tag.name);
+      },
+    },
+    Link: {
+      leave(link: any) {
+        statsAccumulator.links.items!.add(link.operationId);
+      },
+    },
+    Root: {
+      leave() {
+        statsAccumulator.parameters.total = statsAccumulator.parameters.items!.size;
+        statsAccumulator.refs.total = statsAccumulator.refs.items!.size;
+        statsAccumulator.links.total = statsAccumulator.links.items!.size;
+        statsAccumulator.tags.total = statsAccumulator.tags.items!.size;
+      },
+    },
+    WebhooksMap: {
+      Operation: {
+        leave(operation: any) {
+          operation.tags.forEach((tag: string) => {
+            statsAccumulator.tags.items!.add(tag);
+          });
+        },
+      },
+    },
+    Paths: {
+      PathItem: {
+        leave() {
+          statsAccumulator.pathItems.total++;
+        },
+        Operation: {
+          leave(operation: any) {
+            statsAccumulator.operations.total++;
+            operation.tags &&
+              operation.tags.forEach((tag: string) => {
+                statsAccumulator.tags.items!.add(tag);
+              });
+          },
+        },
+        Parameter: {
+          leave(parameter: Oas2Parameter | Oas3Parameter) {
+            statsAccumulator.parameters.items!.add(parameter.name);
+          },
+        },
+      },
+    },
+    NamedSchemas: {
+      Schema: {
+        leave() {
+          statsAccumulator.schemas.total++;
+        },
+      },
+    },
+  };
+};

package/src/rules/utils.ts

@@ -0,0 +1,193 @@
+import levenshtein = require('js-levenshtein');
+import { UserContext } from '../walk';
+import { Location } from '../ref-utils';
+import { validateJsonSchema } from './ajv';
+import { Oas3Schema, Referenced } from '../typings/openapi';
+import { showErrorForDeprecatedField, showWarningForDeprecatedField } from '../utils';
+
+export function oasTypeOf(value: unknown) {
+  if (Array.isArray(value)) {
+    return 'array';
+  } else if (value === null) {
+    return 'null';
+  } else if (Number.isInteger(value)) {
+    return 'integer';
+  } else {
+    return typeof value;
+  }
+}
+
+/**
+ * Checks if value matches specified JSON schema type
+ *
+ * @param {*} value - value to check
+ * @param {JSONSchemaType} type - JSON Schema type
+ * @returns boolean
+ */
+export function matchesJsonSchemaType(value: unknown, type: string, nullable: boolean): boolean {
+  if (nullable && value === null) {
+    return true;
+  }
+
+  switch (type) {
+    case 'array':
+      return Array.isArray(value);
+    case 'object':
+      return typeof value === 'object' && value !== null && !Array.isArray(value);
+    case 'null':
+      return value === null;
+    case 'integer':
+      return Number.isInteger(value);
+    default:
+      return typeof value === type;
+  }
+}
+
+export function missingRequiredField(type: string, field: string): string {
+  return `${type} object should contain \`${field}\` field.`;
+}
+
+export function fieldNonEmpty(type: string, field: string): string {
+  return `${type} object \`${field}\` must be non-empty string.`;
+}
+
+export function validateDefinedAndNonEmpty(fieldName: string, value: any, ctx: UserContext) {
+  if (typeof value !== 'object') {
+    return;
+  }
+
+  if (value[fieldName] === undefined) {
+    ctx.report({
+      message: missingRequiredField(ctx.type.name, fieldName),
+      location: ctx.location.child([fieldName]).key(),
+    });
+  } else if (!value[fieldName]) {
+    ctx.report({
+      message: fieldNonEmpty(ctx.type.name, fieldName),
+      location: ctx.location.child([fieldName]).key(),
+    });
+  }
+}
+
+export function getSuggest(given: string, variants: string[]): string[] {
+  if (given === null) return variants;
+
+  if (typeof given !== 'string' || !variants.length) return [];
+
+  const distances: Array<{ variant: string; distance: number }> = [];
+
+  for (let i = 0; i < variants.length; i++) {
+    const distance = levenshtein(given, variants[i]);
+    if (distance < 4) {
+      distances.push({ distance, variant: variants[i] });
+    }
+  }
+
+  distances.sort((a, b) => a.distance - b.distance);
+
+  // if (bestMatch.distance <= 4) return bestMatch.string;
+  return distances.map((d) => d.variant);
+}
+
+export function validateExample(
+  example: any,
+  schema: Referenced<Oas3Schema>,
+  dataLoc: Location,
+  { resolve, location, report }: UserContext,
+  allowAdditionalProperties: boolean
+) {
+  try {
+    const { valid, errors } = validateJsonSchema(
+      example,
+      schema,
+      location.child('schema'),
+      dataLoc.pointer,
+      resolve,
+      allowAdditionalProperties
+    );
+    if (!valid) {
+      for (const error of errors) {
+        report({
+          message: `Example value must conform to the schema: ${error.message}.`,
+          location: {
+            ...new Location(dataLoc.source, error.instancePath),
+            reportOnKey:
+              error.keyword === 'unevaluatedProperties' || error.keyword === 'additionalProperties',
+          },
+          from: location,
+          suggest: error.suggest,
+        });
+      }
+    }
+  } catch (e) {
+    if (e.message === 'discriminator: requires oneOf or anyOf composite keyword') {
+      return;
+    }
+
+    report({
+      message: `Example validation errored: ${e.message}.`,
+      location: location.child('schema'),
+      from: location,
+    });
+  }
+}
+
+export function getAdditionalPropertiesOption(opts: Record<string, any>): boolean {
+  if (opts.disallowAdditionalProperties === undefined) {
+    return opts.allowAdditionalProperties;
+  }
+
+  if (opts.allowAdditionalProperties !== undefined) {
+    showErrorForDeprecatedField(
+      'disallowAdditionalProperties',
+      'allowAdditionalProperties',
+      undefined
+    );
+  }
+
+  showWarningForDeprecatedField('disallowAdditionalProperties', 'allowAdditionalProperties');
+  return !opts.disallowAdditionalProperties;
+}
+
+export function validateSchemaEnumType(
+  schemaEnum: string[],
+  propertyValue: string,
+  propName: string,
+  refLocation: Location | undefined,
+  { report, location }: UserContext
+) {
+  if (!schemaEnum) {
+    return;
+  }
+  if (!schemaEnum.includes(propertyValue)) {
+    report({
+      location,
+      message: `\`${propName}\` can be one of the following only: ${schemaEnum
+        .map((type) => `"${type}"`)
+        .join(', ')}.`,
+      from: refLocation,
+      suggest: getSuggest(propertyValue, schemaEnum),
+    });
+  }
+}
+
+export function validateResponseCodes(
+  responseCodes: string[],
+  codeRange: string,
+  { report }: UserContext
+) {
+  const responseCodeRegexp = new RegExp(`^${codeRange[0]}[0-9Xx]{2}$`);
+
+  const containsNeededCode = responseCodes.some(
+    (code) =>
+      (codeRange === '2XX' && code === 'default') || // It's OK to replace 2xx codes with the default
+      responseCodeRegexp.test(code)
+  );
+
+  if (!containsNeededCode) {
+    report({
+      message: `Operation must have at least one \`${codeRange}\` response.`,
+      location: { reportOnKey: true },
+    });
+  }
+}