@redocly/openapi-core 1.0.0 → 1.0.1

package/src/rules/common/operation-2xx-response.ts

@@ -0,0 +1,24 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { UserContext } from '../../walk';
+import { validateResponseCodes } from '../utils';
+
+export const Operation2xxResponse: Oas3Rule | Oas2Rule = ({ validateWebhooks }) => {
+  return {
+    Paths: {
+      Responses(responses: Record<string, object>, { report }: UserContext) {
+        const codes = Object.keys(responses || {});
+
+        validateResponseCodes(codes, '2XX', { report } as UserContext);
+      },
+    },
+    WebhooksMap: {
+      Responses(responses: Record<string, object>, { report }: UserContext) {
+        if (!validateWebhooks) return;
+
+        const codes = Object.keys(responses || {});
+
+        validateResponseCodes(codes, '2XX', { report } as UserContext);
+      },
+    },
+  };
+};

package/src/rules/common/operation-4xx-response.ts

@@ -0,0 +1,24 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { UserContext } from '../../walk';
+import { validateResponseCodes } from '../utils';
+
+export const Operation4xxResponse: Oas3Rule | Oas2Rule = ({ validateWebhooks }) => {
+  return {
+    Paths: {
+      Responses(responses: Record<string, object>, { report }: UserContext) {
+        const codes = Object.keys(responses || {});
+
+        validateResponseCodes(codes, '4XX', { report } as UserContext);
+      },
+    },
+    WebhooksMap: {
+      Responses(responses: Record<string, object>, { report }: UserContext) {
+        if (!validateWebhooks) return;
+
+        const codes = Object.keys(responses || {});
+
+        validateResponseCodes(codes, '4XX', { report } as UserContext);
+      },
+    },
+  };
+};

package/src/rules/common/operation-description.ts

@@ -0,0 +1,13 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { validateDefinedAndNonEmpty } from '../utils';
+import { UserContext } from '../../walk';
+import { Oas2Operation } from '../../typings/swagger';
+import { Oas3Operation } from '../../typings/openapi';
+
+export const OperationDescription: Oas3Rule | Oas2Rule = () => {
+  return {
+    Operation(operation: Oas2Operation | Oas3Operation, ctx: UserContext) {
+      validateDefinedAndNonEmpty('description', operation, ctx);
+    },
+  };
+};

package/src/rules/common/operation-operationId-unique.ts

@@ -0,0 +1,21 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { Oas2Operation } from '../../typings/swagger';
+import { Oas3Operation } from '../../typings/openapi';
+import { UserContext } from '../../walk';
+
+export const OperationIdUnique: Oas3Rule | Oas2Rule = () => {
+  const seenOperations = new Set();
+
+  return {
+    Operation(operation: Oas2Operation | Oas3Operation, { report, location }: UserContext) {
+      if (!operation.operationId) return;
+      if (seenOperations.has(operation.operationId)) {
+        report({
+          message: 'Every operation must have a unique `operationId`.',
+          location: location.child([operation.operationId]),
+        });
+      }
+      seenOperations.add(operation.operationId);
+    },
+  };
+};

package/src/rules/common/operation-operationId-url-safe.ts

@@ -0,0 +1,19 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { Oas2Operation } from '../../typings/swagger';
+import { Oas3Operation } from '../../typings/openapi';
+import { UserContext } from '../../walk';
+
+const validUrlSymbols = /^[A-Za-z0-9-._~:/?#\[\]@!\$&'()*+,;=]*$/;
+
+export const OperationIdUrlSafe: Oas3Rule | Oas2Rule = () => {
+  return {
+    Operation(operation: Oas2Operation | Oas3Operation, { report, location }: UserContext) {
+      if (operation.operationId && !validUrlSymbols.test(operation.operationId)) {
+        report({
+          message: 'Operation `operationId` should not have URL invalid characters.',
+          location: location.child(['operationId']),
+        });
+      }
+    },
+  };
+};

package/src/rules/common/operation-operationId.ts

@@ -0,0 +1,17 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { validateDefinedAndNonEmpty } from '../utils';
+import { UserContext } from '../../walk';
+import { Oas2Operation } from '../../typings/swagger';
+import { Oas3Operation } from '../../typings/openapi';
+
+export const OperationOperationId: Oas3Rule | Oas2Rule = () => {
+  return {
+    Root: {
+      PathItem: {
+        Operation(operation: Oas2Operation | Oas3Operation, ctx: UserContext) {
+          validateDefinedAndNonEmpty('operationId', operation, ctx);
+        },
+      },
+    },
+  };
+};

package/src/rules/common/operation-parameters-unique.ts

@@ -0,0 +1,48 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { Oas2Parameter } from '../../typings/swagger';
+import { Oas3Parameter } from '../../typings/openapi';
+import { UserContext } from '../../walk';
+
+export const OperationParametersUnique: Oas3Rule | Oas2Rule = () => {
+  let seenPathParams: Set<string>;
+  let seenOperationParams: Set<string>;
+
+  return {
+    PathItem: {
+      enter() {
+        seenPathParams = new Set();
+      },
+      Parameter(
+        parameter: Oas2Parameter | Oas3Parameter,
+        { report, key, parentLocations }: UserContext
+      ) {
+        const paramId = `${parameter.in}___${parameter.name}`;
+        if (seenPathParams.has(paramId)) {
+          report({
+            message: `Paths must have unique \`name\` + \`in\` parameters.\nRepeats of \`in:${parameter.in}\` + \`name:${parameter.name}\`.`,
+            location: parentLocations.PathItem.child(['parameters', key]),
+          });
+        }
+        seenPathParams.add(`${parameter.in}___${parameter.name}`);
+      },
+      Operation: {
+        enter() {
+          seenOperationParams = new Set();
+        },
+        Parameter(
+          parameter: Oas2Parameter | Oas3Parameter,
+          { report, key, parentLocations }: UserContext
+        ) {
+          const paramId = `${parameter.in}___${parameter.name}`;
+          if (seenOperationParams.has(paramId)) {
+            report({
+              message: `Operations must have unique \`name\` + \`in\` parameters. Repeats of \`in:${parameter.in}\` + \`name:${parameter.name}\`.`,
+              location: parentLocations.Operation.child(['parameters', key]),
+            });
+          }
+          seenOperationParams.add(paramId);
+        },
+      },
+    },
+  };
+};

package/src/rules/common/operation-singular-tag.ts

@@ -0,0 +1,17 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { Oas2Operation } from '../../typings/swagger';
+import { Oas3Operation } from '../../typings/openapi';
+import { UserContext } from '../../walk';
+
+export const OperationSingularTag: Oas3Rule | Oas2Rule = () => {
+  return {
+    Operation(operation: Oas2Operation | Oas3Operation, { report, location }: UserContext) {
+      if (operation.tags && operation.tags.length > 1) {
+        report({
+          message: 'Operation `tags` object should have only one tag.',
+          location: location.child(['tags']).key(),
+        });
+      }
+    },
+  };
+};

package/src/rules/common/operation-summary.ts

@@ -0,0 +1,13 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { validateDefinedAndNonEmpty } from '../utils';
+import { UserContext } from '../../walk';
+import { Oas2Operation } from '../../typings/swagger';
+import { Oas3Operation } from '../../typings/openapi';
+
+export const OperationSummary: Oas3Rule | Oas2Rule = () => {
+  return {
+    Operation(operation: Oas2Operation | Oas3Operation, ctx: UserContext) {
+      validateDefinedAndNonEmpty('summary', operation, ctx);
+    },
+  };
+};

package/src/rules/common/operation-tag-defined.ts

@@ -0,0 +1,26 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { Oas2Definition, Oas2Operation } from '../../typings/swagger';
+import { Oas3Definition, Oas3Operation } from '../../typings/openapi';
+import { UserContext } from '../../walk';
+
+export const OperationTagDefined: Oas3Rule | Oas2Rule = () => {
+  let definedTags: Set<string>;
+
+  return {
+    Root(root: Oas2Definition | Oas3Definition) {
+      definedTags = new Set((root.tags ?? []).map((t) => t.name));
+    },
+    Operation(operation: Oas2Operation | Oas3Operation, { report, location }: UserContext) {
+      if (operation.tags) {
+        for (let i = 0; i < operation.tags.length; i++) {
+          if (!definedTags.has(operation.tags[i])) {
+            report({
+              message: `Operation tags should be defined in global tags.`,
+              location: location.child(['tags', i]),
+            });
+          }
+        }
+      }
+    },
+  };
+};

package/src/rules/common/parameter-description.ts

@@ -0,0 +1,22 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { Oas2Parameter } from '../../typings/swagger';
+import { Oas3Parameter } from '../../typings/openapi';
+import { UserContext } from '../../walk';
+
+export const ParameterDescription: Oas3Rule | Oas2Rule = () => {
+  return {
+    Parameter(parameter: Oas2Parameter | Oas3Parameter, { report, location }: UserContext) {
+      if (parameter.description === undefined) {
+        report({
+          message: 'Parameter object description must be present.',
+          location: { reportOnKey: true },
+        });
+      } else if (!parameter.description) {
+        report({
+          message: 'Parameter object description must be non-empty string.',
+          location: location.child(['description']),
+        });
+      }
+    },
+  };
+};

package/src/rules/common/path-declaration-must-exist.ts

@@ -0,0 +1,15 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { UserContext } from '../../walk';
+
+export const PathDeclarationMustExist: Oas3Rule | Oas2Rule = () => {
+  return {
+    PathItem(_path: object, { report, key }: UserContext) {
+      if ((key as string).indexOf('{}') !== -1) {
+        report({
+          message: 'Path parameter declarations must be non-empty. `{}` is invalid.',
+          location: { reportOnKey: true },
+        });
+      }
+    },
+  };
+};

package/src/rules/common/path-excludes-patterns.ts

@@ -0,0 +1,23 @@
+import { Oas2Rule, Oas3Rule } from '../../visitors';
+import { Oas2PathItem } from '../../typings/swagger';
+import { Oas3PathItem } from '../../typings/openapi';
+import { UserContext } from '../../walk';
+
+export const PathExcludesPatterns: Oas3Rule | Oas2Rule = ({ patterns }) => {
+  return {
+    PathItem(_path: Oas2PathItem | Oas3PathItem, { report, key, location }: UserContext) {
+      if (!patterns)
+        throw new Error(`Parameter "patterns" is not provided for "path-excludes-patterns" rule`);
+      const pathKey = key.toString();
+      if (pathKey.startsWith('/')) {
+        const matches = patterns.filter((pattern: string) => pathKey.match(pattern));
+        for (const match of matches) {
+          report({
+            message: `path \`${pathKey}\` should not match regex pattern: \`${match}\``,
+            location: location.key(),
+          });
+        }
+      }
+    },
+  };
+};

package/src/rules/common/path-http-verbs-order.ts

@@ -0,0 +1,30 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { Oas2PathItem } from '../../typings/swagger';
+import { Oas3PathItem } from '../../typings/openapi';
+import { UserContext } from '../../walk';
+
+const defaultOrder = ['get', 'head', 'post', 'put', 'patch', 'delete', 'options', 'trace'];
+
+export const PathHttpVerbsOrder: Oas3Rule | Oas2Rule = (opts: any) => {
+  const order: string[] = (opts && opts.order) || defaultOrder;
+  if (!Array.isArray(order)) {
+    throw new Error('path-http-verbs-order `order` option must be an array');
+  }
+
+  return {
+    PathItem(path: Oas2PathItem | Oas3PathItem, { report, location }: UserContext) {
+      const httpVerbs = Object.keys(path).filter((k) => order.includes(k));
+
+      for (let i = 0; i < httpVerbs.length - 1; i++) {
+        const aIdx = order.indexOf(httpVerbs[i]);
+        const bIdx = order.indexOf(httpVerbs[i + 1]);
+        if (bIdx < aIdx) {
+          report({
+            message: 'Operation http verbs must be ordered.',
+            location: { reportOnKey: true, ...location.child(httpVerbs[i + 1]) },
+          });
+        }
+      }
+    },
+  };
+};

package/src/rules/common/path-not-include-query.ts

@@ -0,0 +1,17 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { UserContext } from '../../walk';
+
+export const PathNotIncludeQuery: Oas3Rule | Oas2Rule = () => {
+  return {
+    Paths: {
+      PathItem(_operation: object, { report, key }: UserContext) {
+        if (key.toString().includes('?')) {
+          report({
+            message: `Don't put query string items in the path, they belong in parameters with \`in: query\`.`,
+            location: { reportOnKey: true },
+          });
+        }
+      },
+    },
+  };
+};

package/src/rules/common/path-params-defined.ts

@@ -0,0 +1,65 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { Oas2Parameter } from '../../typings/swagger';
+import { Oas3Parameter } from '../../typings/openapi';
+import { UserContext } from '../../walk';
+
+const pathRegex = /\{([a-zA-Z0-9_.-]+)\}+/g;
+
+export const PathParamsDefined: Oas3Rule | Oas2Rule = () => {
+  let pathTemplateParams: Set<string>;
+  let definedPathParams: Set<string>;
+  let currentPath: string;
+  let definedOperationParams: Set<string>;
+
+  return {
+    PathItem: {
+      enter(_: object, { key }: UserContext) {
+        definedPathParams = new Set();
+        currentPath = key as string;
+        pathTemplateParams = new Set(
+          Array.from(key!.toString().matchAll(pathRegex)).map((m) => m[1])
+        );
+      },
+      Parameter(parameter: Oas2Parameter | Oas3Parameter, { report, location }: UserContext) {
+        if (parameter.in === 'path' && parameter.name) {
+          definedPathParams.add(parameter.name);
+          if (!pathTemplateParams.has(parameter.name)) {
+            report({
+              message: `Path parameter \`${parameter.name}\` is not used in the path \`${currentPath}\`.`,
+              location: location.child(['name']),
+            });
+          }
+        }
+      },
+      Operation: {
+        enter() {
+          definedOperationParams = new Set();
+        },
+        leave(_op: object, { report, location }: UserContext) {
+          for (const templateParam of Array.from(pathTemplateParams.keys())) {
+            if (
+              !definedOperationParams.has(templateParam) &&
+              !definedPathParams.has(templateParam)
+            ) {
+              report({
+                message: `The operation does not define the path parameter \`{${templateParam}}\` expected by path \`${currentPath}\`.`,
+                location: location.child(['parameters']).key(), // report on operation
+              });
+            }
+          }
+        },
+        Parameter(parameter: Oas2Parameter | Oas3Parameter, { report, location }: UserContext) {
+          if (parameter.in === 'path' && parameter.name) {
+            definedOperationParams.add(parameter.name);
+            if (!pathTemplateParams.has(parameter.name)) {
+              report({
+                message: `Path parameter \`${parameter.name}\` is not used in the path \`${currentPath}\`.`,
+                location: location.child(['name']),
+              });
+            }
+          }
+        },
+      },
+    },
+  };
+};

package/src/rules/common/path-segment-plural.ts

@@ -0,0 +1,31 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { UserContext } from '../../walk';
+import { isPathParameter, isSingular } from '../../utils';
+
+export const PathSegmentPlural: Oas3Rule | Oas2Rule = (opts) => {
+  const { ignoreLastPathSegment, exceptions } = opts;
+  return {
+    PathItem: {
+      leave(_path: any, { report, key, location }: UserContext) {
+        const pathKey = key.toString();
+        if (pathKey.startsWith('/')) {
+          const pathSegments = pathKey.split('/');
+          pathSegments.shift();
+          if (ignoreLastPathSegment && pathSegments.length > 1) {
+            pathSegments.pop();
+          }
+
+          for (const pathSegment of pathSegments) {
+            if (exceptions && exceptions.includes(pathSegment)) continue;
+            if (!isPathParameter(pathSegment) && isSingular(pathSegment)) {
+              report({
+                message: `path segment \`${pathSegment}\` should be plural.`,
+                location: location.key(),
+              });
+            }
+          }
+        }
+      },
+    },
+  };
+};

package/src/rules/common/paths-kebab-case.ts

@@ -0,0 +1,19 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { UserContext } from '../../walk';
+
+export const PathsKebabCase: Oas3Rule | Oas2Rule = () => {
+  return {
+    PathItem(_path: object, { report, key }: UserContext) {
+      const segments = (key as string)
+        .substr(1)
+        .split('/')
+        .filter((s) => s !== ''); // filter out empty segments
+      if (!segments.every((segment) => /^{.+}$/.test(segment) || /^[a-z0-9-.]+$/.test(segment))) {
+        report({
+          message: `\`${key}\` does not use kebab-case.`,
+          location: { reportOnKey: true },
+        });
+      }
+    },
+  };
+};

package/src/rules/common/required-string-property-missing-min-length.ts

@@ -0,0 +1,44 @@
+import { UserContext } from '../../walk';
+import { Oas3Schema, Oas3_1Schema } from '../../typings/openapi';
+import { Oas2Schema } from 'core/src/typings/swagger';
+import { Oas3Rule } from 'core/src/visitors';
+
+export const RequiredStringPropertyMissingMinLength: Oas3Rule = () => {
+  let skipSchemaProperties: boolean;
+  let requiredPropertiesSet: Set<string>;
+
+  return {
+    Schema: {
+      enter(schema: Oas3Schema | Oas3_1Schema | Oas2Schema) {
+        if (!schema?.required) {
+          skipSchemaProperties = true;
+          return;
+        }
+        requiredPropertiesSet = new Set(schema.required);
+        skipSchemaProperties = false;
+      },
+
+      SchemaProperties: {
+        skip() {
+          return skipSchemaProperties;
+        },
+
+        Schema: {
+          enter(
+            schema: Oas3Schema | Oas3_1Schema | Oas2Schema,
+            { key, location, report }: UserContext
+          ) {
+            if (requiredPropertiesSet.has(key as string) && schema.type === 'string') {
+              if (!schema?.minLength) {
+                report({
+                  message: 'Property minLength is required.',
+                  location: location.key(),
+                });
+              }
+            }
+          },
+        },
+      },
+    },
+  };
+};

package/src/rules/common/response-contains-header.ts

@@ -0,0 +1,35 @@
+import { Oas2Rule, Oas3Rule } from '../../visitors';
+import { UserContext } from '../../walk';
+import { Oas3Response } from '../../typings/openapi';
+import { Oas2Response } from '../../typings/swagger';
+import { getMatchingStatusCodeRange } from '../../utils';
+
+export const ResponseContainsHeader: Oas3Rule | Oas2Rule = (options) => {
+  const names: Record<string, string[]> = options.names || {};
+  return {
+    Operation: {
+      Response: {
+        enter: (response: Oas2Response | Oas3Response, { report, location, key }: UserContext) => {
+          const expectedHeaders =
+            names[key] ||
+            names[getMatchingStatusCodeRange(key)] ||
+            names[getMatchingStatusCodeRange(key).toLowerCase()] ||
+            [];
+          for (const expectedHeader of expectedHeaders) {
+            if (
+              !response?.headers ||
+              !Object.keys(response?.headers).some(
+                (header) => header.toLowerCase() === expectedHeader.toLowerCase()
+              )
+            ) {
+              report({
+                message: `Response object must contain a "${expectedHeader}" header.`,
+                location: location.child('headers').key(),
+              });
+            }
+          }
+        },
+      },
+    },
+  };
+};

package/src/rules/common/scalar-property-missing-example.ts

@@ -0,0 +1,58 @@
+import type { Oas2Rule, Oas3Rule } from '../../visitors';
+import type { UserContext } from '../../walk';
+import type { Oas2Schema } from '../../typings/swagger';
+import type { Oas3Schema, Oas3_1Schema } from '../../typings/openapi';
+import { OasVersion } from '../../oas-types';
+
+const SCALAR_TYPES = ['string', 'integer', 'number', 'boolean', 'null'];
+
+export const ScalarPropertyMissingExample: Oas3Rule | Oas2Rule = () => {
+  return {
+    SchemaProperties(
+      properties: { [name: string]: Oas2Schema | Oas3Schema | Oas3_1Schema },
+      { report, location, oasVersion, resolve }: UserContext
+    ) {
+      for (const propName of Object.keys(properties)) {
+        const propSchema = resolve(properties[propName]).node;
+
+        if (!propSchema || !isScalarSchema(propSchema)) {
+          continue;
+        }
+
+        if (
+          propSchema.example === undefined &&
+          (propSchema as Oas3_1Schema).examples === undefined
+        ) {
+          report({
+            message: `Scalar property should have "example"${
+              oasVersion === OasVersion.Version3_1 ? ' or "examples"' : ''
+            } defined.`,
+            location: location.child(propName).key(),
+          });
+        }
+      }
+    },
+  };
+};
+
+function isScalarSchema(schema: Oas2Schema | Oas3Schema | Oas3_1Schema) {
+  if (!schema.type) {
+    return false;
+  }
+
+  if (schema.allOf || (schema as Oas3Schema).anyOf || (schema as Oas3Schema).oneOf) {
+    // Skip allOf/oneOf/anyOf as it's complicated to validate it right now.
+    // We need core support for checking contrstrains through those keywords.
+    return false;
+  }
+
+  if (schema.format === 'binary') {
+    return false;
+  }
+
+  if (Array.isArray(schema.type)) {
+    return schema.type.every((t) => SCALAR_TYPES.includes(t));
+  }
+
+  return SCALAR_TYPES.includes(schema.type);
+}

package/src/rules/common/security-defined.ts

@@ -0,0 +1,65 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { Location } from '../../ref-utils';
+import { UserContext } from '../../walk';
+import { Oas2Definition, Oas2Operation, Oas2SecurityScheme } from '../../typings/swagger';
+import { Oas3Definition, Oas3Operation, Oas3SecurityScheme } from '../../typings/openapi';
+
+export const SecurityDefined: Oas3Rule | Oas2Rule = () => {
+  const referencedSchemes = new Map<
+    string,
+    {
+      defined?: boolean;
+      from: Location[];
+    }
+  >();
+
+  const operationsWithoutSecurity: Location[] = [];
+  let eachOperationHasSecurity: boolean = true;
+
+  return {
+    Root: {
+      leave(root: Oas2Definition | Oas3Definition, { report }: UserContext) {
+        for (const [name, scheme] of referencedSchemes.entries()) {
+          if (scheme.defined) continue;
+          for (const reportedFromLocation of scheme.from) {
+            report({
+              message: `There is no \`${name}\` security scheme defined.`,
+              location: reportedFromLocation.key(),
+            });
+          }
+        }
+
+        if (root.security || eachOperationHasSecurity) {
+          return;
+        } else {
+          for (const operationLocation of operationsWithoutSecurity) {
+            report({
+              message: `Every operation should have security defined on it or on the root level.`,
+              location: operationLocation.key(),
+            });
+          }
+        }
+      },
+    },
+    SecurityScheme(_securityScheme: Oas2SecurityScheme | Oas3SecurityScheme, { key }: UserContext) {
+      referencedSchemes.set(key.toString(), { defined: true, from: [] });
+    },
+    SecurityRequirement(requirements, { location }) {
+      for (const requirement of Object.keys(requirements)) {
+        const authScheme = referencedSchemes.get(requirement);
+        const requirementLocation = location.child([requirement]);
+        if (!authScheme) {
+          referencedSchemes.set(requirement, { from: [requirementLocation] });
+        } else {
+          authScheme.from.push(requirementLocation);
+        }
+      }
+    },
+    Operation(operation: Oas2Operation | Oas3Operation, { location }: UserContext) {
+      if (!operation?.security) {
+        eachOperationHasSecurity = false;
+        operationsWithoutSecurity.push(location);
+      }
+    },
+  };
+};