@redocly/openapi-core 1.0.0-beta.100

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 = () => {
+  let 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,
+        });
+      }
+    },
+    DefinitionRoot: {
+      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/remove-unused-components.ts

@@ -0,0 +1,84 @@
+import { Oas3Rule } from '../../visitors';
+import { Location } from '../../ref-utils';
+import { Oas3Components } from '../../typings/openapi'
+import { isEmptyObject } from '../../utils';
+
+export const RemoveUnusedComponents: Oas3Rule = () => {
+  let 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(),
+          });
+        }
+      }
+    },
+    DefinitionRoot: {
+      leave(root, ctx) {
+        const data = ctx.getVisitorData() as { removedCount: number };
+        data.removedCount = 0;
+
+        components.forEach(usageInfo => {
+          const { used, componentType, name } = usageInfo;
+          if (!used && componentType) {
+            let 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,31 @@
+import { Oas3Rule } from '../../visitors';
+import { UserContext } from '../../walk';
+import { Oas3RequestBody, Oas3Response } from '../../typings/openapi';
+import { validateMimeTypeOAS3 } from '../../utils';
+
+export const RequestMimeType: Oas3Rule = ({ allowedValues }) => {
+  return {
+    PathMap: {
+      RequestBody: {
+        leave(requestBody: Oas3RequestBody, ctx: UserContext) {
+          validateMimeTypeOAS3({ type: 'consumes', value: requestBody }, ctx, allowedValues);
+        },
+      },
+      Callback: {
+        RequestBody() {},
+        Response: {
+          leave(response: Oas3Response, ctx: UserContext) {
+            validateMimeTypeOAS3({ type: 'consumes', value: response }, ctx, allowedValues);
+          },
+        },
+      },
+    },
+    WebhooksMap: {
+      Response: {
+        leave(response: Oas3Response, 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,31 @@
+import { Oas3Rule } from '../../visitors';
+import { UserContext } from '../../walk';
+import { Oas3RequestBody, Oas3Response } from '../../typings/openapi';
+import { validateMimeTypeOAS3 } from '../../utils';
+
+export const ResponseMimeType: Oas3Rule = ({ allowedValues }) => {
+  return {
+    PathMap: {
+      Response: {
+        leave(response: Oas3Response, ctx: UserContext) {
+          validateMimeTypeOAS3({ type: 'produces', value: response }, ctx, allowedValues);
+        },
+      },
+      Callback: {
+        Response() {},
+        RequestBody: {
+          leave(requestBody: Oas3RequestBody, ctx: UserContext) {
+            validateMimeTypeOAS3({ type: 'produces', value: requestBody }, ctx, allowedValues);
+          },
+        },
+      },
+    },
+    WebhooksMap: {
+      RequestBody: {
+        leave(requestBody: Oas3RequestBody, ctx: UserContext) {
+          validateMimeTypeOAS3({ type: 'produces', value: requestBody }, ctx, allowedValues);
+        },
+      },
+    },
+  };
+};

package/src/rules/other/stats.ts

@@ -0,0 +1,44 @@
+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); }},
+    DefinitionRoot: {
+      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); })
+        }
+      }
+    },
+    PathMap: {
+      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,123 @@
+import levenshtein = require('js-levenshtein');
+import { UserContext } from '../walk';
+import { Location } from '../ref-utils';
+import { validateJsonSchema } from './ajv';
+import { Oas3Schema, Referenced } from '../typings/openapi';
+
+export function oasTypeOf(value: unknown) {
+  if (Array.isArray(value)) {
+    return 'array';
+  } else if (value === null) {
+    return 'null';
+  } 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 value === null;
+  }
+
+  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 (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,
+  disallowAdditionalProperties: boolean,
+) {
+  try {
+    const { valid, errors } = validateJsonSchema(
+      example,
+      schema,
+      location.child('schema'),
+      dataLoc.pointer,
+      resolve,
+      disallowAdditionalProperties,
+    );
+    if (!valid) {
+      for (let error of errors) {
+        report({
+          message: `Example value must conform to the schema: ${error.message}.`,
+          location: {
+            ...new Location(dataLoc.source, error.instancePath),
+            reportOnKey: error.keyword === 'additionalProperties',
+          },
+          from: location,
+          suggest: error.suggest,
+        });
+      }
+    }
+  } catch (e) {
+    report({
+      message: `Example validation errored: ${e.message}.`,
+      location: location.child('schema'),
+      from: location,
+    });
+  }
+}

package/src/types/index.ts

@@ -0,0 +1,138 @@
+export type ScalarSchema = {
+  name?: never;
+  type?: 'string' | 'boolean' | 'number' | 'integer' | 'object' | 'array';
+  items?: ScalarSchema;
+  enum?: string[];
+  isExample?: boolean;
+  directResolveAs?: string;
+  minimum?: number;
+};
+
+export type NormalizedScalarSchema = {
+  name?: never;
+  type?: 'string' | 'boolean' | 'number' | 'integer' | 'object' | 'array';
+  items?: ScalarSchema;
+  enum?: string[];
+  directResolveAs?: NormalizedNodeType;
+  resolvable: boolean;
+  minimum?: number;
+};
+
+export type NodeType = {
+  properties: Record<string, PropType | ResolveTypeFn>;
+  additionalProperties?: PropType | ResolveTypeFn;
+  items?: string;
+  required?: string[] | ((value: any, key: string | number | undefined) => string[]);
+  requiredOneOf?: string[];
+  allowed?: ((value: any) => string[] | undefined);
+  extensionsPrefix?: string;
+};
+type PropType = string | NodeType | ScalarSchema | undefined | null;
+type ResolveTypeFn = (value: any, key: string) => string | PropType;
+
+export type NormalizedNodeType = {
+  name: string;
+  properties: Record<string, NormalizedPropType | NormalizedResolveTypeFn>;
+  additionalProperties?: NormalizedPropType | NormalizedResolveTypeFn;
+  items?: NormalizedNodeType;
+  required?: string[] | ((value: any, key: string | number | undefined) => string[]);
+  requiredOneOf?: string[];
+  allowed?: ((value: any) => string[] | undefined);
+  extensionsPrefix?: string;
+};
+
+type NormalizedPropType = NormalizedNodeType | NormalizedScalarSchema | undefined | null;
+type NormalizedResolveTypeFn = (
+  value: any,
+  key: string,
+) => NormalizedNodeType | NormalizedScalarSchema | undefined | null;
+
+export function listOf(typeName: string) {
+  return {
+    name: `${typeName}List`,
+    properties: {},
+    items: typeName,
+  };
+}
+
+export function mapOf(typeName: string) {
+  return {
+    name: `${typeName}Map`,
+    properties: {},
+    additionalProperties: () => typeName,
+  };
+}
+
+export function normalizeTypes(
+  types: Record<string, NodeType>,
+  options: { doNotResolveExamples?: boolean } = {},
+): Record<string, NormalizedNodeType> {
+  const normalizedTypes: Record<string, NormalizedNodeType> = {};
+
+  for (const typeName of Object.keys(types)) {
+    normalizedTypes[typeName] = {
+      ...types[typeName],
+      name: typeName,
+    } as any;
+  }
+
+  for (const type of Object.values(normalizedTypes)) {
+    normalizeType(type);
+  }
+  return normalizedTypes;
+
+  function normalizeType(type: any) {
+    if (type.additionalProperties) {
+      type.additionalProperties = resolveType(type.additionalProperties);
+    }
+    if (type.items) {
+      type.items = resolveType(type.items);
+    }
+
+    if (type.properties) {
+      const mappedProps: Record<string, any> = {};
+      for (const [propName, prop] of Object.entries(type.properties)) {
+        mappedProps[propName] = resolveType(prop);
+
+        if (options.doNotResolveExamples && prop && (prop as ScalarSchema).isExample) {
+          mappedProps[propName] = {
+            ...(prop as object),
+            resolvable: false,
+          };
+        }
+      }
+      type.properties = mappedProps;
+    }
+  }
+
+  // typings are painful here...
+  function resolveType(type?: any): any {
+    if (typeof type === 'string') {
+      if (!normalizedTypes[type]) {
+        throw new Error(`Unknown type name found: ${type}`);
+      }
+      return normalizedTypes[type];
+    } else if (typeof type === 'function') {
+      return (value: any, key: string) => {
+        return resolveType(type(value, key));
+      };
+    } else if (type && type.name) {
+      type = { ...type };
+      normalizeType(type);
+      return type;
+    } else if (type && type.directResolveAs) {
+      return {
+        ...type,
+        directResolveAs: resolveType(type.directResolveAs),
+      };
+    } else {
+      return type;
+    }
+  }
+}
+
+export function isNamedType(
+  t: NormalizedNodeType | NormalizedScalarSchema | null | undefined,
+): t is NormalizedNodeType {
+  return typeof t?.name === 'string';
+}