@redocly/openapi-core 1.0.0-beta.66 → 1.0.0-beta.70

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

@@ -0,0 +1,108 @@
+import { outdent } from 'outdent';
+import { lintDocument } from '../../../lint';
+import { parseYamlToDocument, replaceSourceWithRef } from '../../../../__tests__/utils';
+import { makeConfig } from '../../__tests__/config';
+import { BaseResolver } from '../../../resolve';
+
+describe('Oas3 operation-4xx-response', () => {
+  it('should report missing 4xx response', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.0.0
+          paths:
+            '/test':
+              put:
+                responses:
+                  200:
+                    description: ok response
+        `,
+      'foobar.yaml',
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: makeConfig({ 'operation-4xx-response': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/paths/~1test/put/responses",
+              "reportOnKey": true,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Operation must have at least one \`4xx\` response.",
+          "ruleId": "operation-4xx-response",
+          "severity": "error",
+          "suggest": Array [],
+        },
+      ]
+    `);
+  });
+
+  it('should not report for present 4xx response', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.0.0
+          paths:
+            '/test/':
+              put:
+                responses:
+                  400:
+                    description: error response
+        `,
+      'foobar.yaml',
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: makeConfig({ 'operation-4xx-response': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`Array []`);
+  });
+
+  it('should report if default is present but missing 4xx response', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.0.0
+          paths:
+            '/test/':
+              put:
+                responses:
+                  default:
+                    description: some default response
+        `,
+      'foobar.yaml',
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: makeConfig({ 'operation-4xx-response': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/paths/~1test~1/put/responses",
+              "reportOnKey": true,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Operation must have at least one \`4xx\` response.",
+          "ruleId": "operation-4xx-response",
+          "severity": "error",
+          "suggest": Array [],
+        },
+      ]
+    `);
+  });
+});

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

@@ -83,4 +83,27 @@ describe('Oas3 paths-kebab-case', () => {
       ]
     `);
   });
+
+  it('should allow trailing slash in path with "paths-kebab-case" rule', async () => {
+      const document = parseYamlToDocument(
+        outdent`
+            openapi: 3.0.0
+            paths:
+              /some/:
+                get:
+                  summary: List all pets
+          `,
+        'foobar.yaml',
+      );
+
+      const results = await lintDocument({
+        externalRefResolver: new BaseResolver(),
+        document,
+        config: makeConfig({
+          'paths-kebab-case': 'error',
+          'no-path-trailing-slash': 'off',
+        }),
+      });
+      expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`Array []`);
+    });
 });

package/src/rules/common/no-invalid-parameter-examples.ts

@@ -0,0 +1,36 @@
+import { UserContext } from '../../walk';
+import { Oas3Parameter } from '../../typings/openapi';
+import { validateExample } from '../utils';
+
+export const NoInvalidParameterExamples: any = (opts: any) => {
+  const disallowAdditionalProperties = opts.disallowAdditionalProperties ?? true;
+  return {
+    Parameter: {
+      leave(parameter: Oas3Parameter, ctx: UserContext) {
+        if (parameter.example) {
+          validateExample(
+            parameter.example,
+            parameter.schema!,
+            ctx.location.child('example'),
+            ctx,
+            disallowAdditionalProperties,
+          );
+        }
+
+        if (parameter.examples) {
+          for (const [key, example] of Object.entries(parameter.examples)) {
+            if ('value' in example) {
+              validateExample(
+                example.value,
+                parameter.schema!,
+                ctx.location.child(['examples', key]),
+                ctx,
+                false,
+              );
+            }
+          }
+        }
+      },
+    },
+  };
+};

package/src/rules/common/no-invalid-schema-examples.ts

@@ -0,0 +1,27 @@
+import { UserContext } from '../../walk';
+import { Oas3_1Schema } from '../../typings/openapi';
+import { validateExample } from '../utils';
+
+export const NoInvalidSchemaExamples: any = (opts: any) => {
+  const disallowAdditionalProperties = opts.disallowAdditionalProperties ?? true;
+  return {
+    Schema: {
+      leave(schema: Oas3_1Schema, ctx: UserContext) {
+        if (schema.examples) {
+          for (const example of schema.examples) {
+            validateExample(
+              example,
+              schema,
+              ctx.location.child(['examples', schema.examples.indexOf(example)]),
+              ctx,
+              disallowAdditionalProperties,
+            );
+          }
+        }
+        if (schema.example) {
+          validateExample(schema.example, schema, ctx.location.child('example'), ctx, false);
+        }
+      },
+    },
+  };
+};

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

@@ -0,0 +1,17 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { UserContext } from '../../walk';
+
+export const Operation4xxResponse: Oas3Rule | Oas2Rule = () => {
+  return {
+    ResponsesMap(responses: Record<string, object>, { report }: UserContext) {
+      const codes = Object.keys(responses);
+
+      if (!codes.some((code) => /4[Xx0-9]{2}/.test(code))) {
+        report({
+          message: 'Operation must have at least one `4xx` response.',
+          location: { reportOnKey: true },
+        });
+      }
+    },
+  };
+};

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

@@ -4,7 +4,7 @@ import { UserContext } from '../../walk';
 export const PathsKebabCase: Oas3Rule | Oas2Rule = () => {
   return {
     PathItem(_path: object, { report, key }: UserContext) {
-      const segments = (key as string).substr(1).split('/');
+      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.`,

package/src/rules/common/registry-dependencies.ts

@@ -1,24 +1,22 @@
-import { RedoclyClient } from '../../redocly';
+import { UserContext } from '../../walk';
+import { isRedoclyRegistryURL } from '../../redocly';
 
 import { Oas3Decorator, Oas2Decorator } from '../../visitors';
 
 export const RegistryDependencies: Oas3Decorator | Oas2Decorator = () => {
-  let redoclyClient: RedoclyClient;
   let registryDependencies = new Set<string>();
 
   return {
     DefinitionRoot: {
-      leave() {
-        redoclyClient = new RedoclyClient();
-        if (process.env.UPDATE_REGISTRY && redoclyClient.hasToken()) {
-          redoclyClient.updateDependencies(Array.from(registryDependencies.keys()));
-        }
+      leave(_: any, ctx: UserContext) {
+        const data = ctx.getVisitorData();
+        data.links = Array.from(registryDependencies);
       },
     },
     ref(node) {
       if (node.$ref) {
         const link = node.$ref.split('#/')[0];
-        if (RedoclyClient.isRegistryURL(link)) {
+        if (isRedoclyRegistryURL(link)) {
           registryDependencies.add(link);
         }
       }

package/src/rules/oas2/index.ts

@@ -1,4 +1,6 @@
 import { OasSpec } from '../common/spec';
+import { NoInvalidSchemaExamples } from '../common/no-invalid-schema-examples';
+import { NoInvalidParameterExamples } from '../common/no-invalid-parameter-examples';
 import { InfoDescription } from '../common/info-description';
 import { InfoContact } from '../common/info-contact';
 import { InfoLicense } from '../common/info-license-url';
@@ -10,6 +12,7 @@ import { PathsKebabCase } from '../common/paths-kebab-case';
 import { NoEnumTypeMismatch } from '../common/no-enum-type-mismatch';
 import { NoPathTrailingSlash } from '../common/no-path-trailing-slash';
 import { Operation2xxResponse } from '../common/operation-2xx-response';
+import { Operation4xxResponse } from '../common/operation-4xx-response';
 import { OperationIdUnique } from '../common/operation-operationId-unique';
 import { OperationParametersUnique } from '../common/operation-parameters-unique';
 import { PathParamsDefined } from '../common/path-params-defined';
@@ -40,6 +43,8 @@ import { InfoDescriptionOverride } from '../common/info-description-override';
 
 export const rules = {
   spec: OasSpec as Oas2Rule,
+  'no-invalid-schema-examples': NoInvalidSchemaExamples,
+  'no-invalid-parameter-examples': NoInvalidParameterExamples,
   'info-description': InfoDescription as Oas2Rule,
   'info-contact': InfoContact as Oas2Rule,
   'info-license': InfoLicense as Oas2Rule,
@@ -51,6 +56,7 @@ export const rules = {
   'boolean-parameter-prefixes': BooleanParameterPrefixes as Oas2Rule,
   'no-path-trailing-slash': NoPathTrailingSlash as Oas2Rule,
   'operation-2xx-response': Operation2xxResponse as Oas2Rule,
+  'operation-4xx-response': Operation4xxResponse as Oas2Rule,
   'operation-operationId-unique': OperationIdUnique as Oas2Rule,
   'operation-parameters-unique': OperationParametersUnique as Oas2Rule,
   'path-parameters-defined': PathParamsDefined as Oas2Rule,

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

@@ -58,4 +58,23 @@ describe('Oas3 oas3-no-server-trailing-slash', () => {
 
     expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`Array []`);
   });
+
+  it('oas3-no-server-trailing-slash: should not report on server object with no trailing slash if the url is root', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.0.0
+          servers:
+            - url: /
+        `,
+      'foobar.yaml',
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: makeConfig({ 'no-server-trailing-slash': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`Array []`);
+  });
 });

package/src/rules/oas3/index.ts

@@ -2,6 +2,7 @@ import { Oas3RuleSet } from '../../oas-types';
 import { Oas3Decorator } from '../../visitors';
 import { OasSpec } from '../common/spec';
 import { Operation2xxResponse } from '../common/operation-2xx-response';
+import { Operation4xxResponse } from '../common/operation-4xx-response';
 import { OperationIdUnique } from '../common/operation-operationId-unique';
 import { OperationParametersUnique } from '../common/operation-parameters-unique';
 import { PathParamsDefined } from '../common/path-params-defined';
@@ -46,6 +47,8 @@ import { OperationDescriptionOverride } from '../common/operation-description-ov
 import { TagDescriptionOverride } from '../common/tag-description-override';
 import { InfoDescriptionOverride } from '../common/info-description-override';
 import { PathExcludesPatterns } from '../common/path-excludes-patterns';
+import { NoInvalidSchemaExamples } from '../common/no-invalid-schema-examples';
+import { NoInvalidParameterExamples } from '../common/no-invalid-parameter-examples';
 
 export const rules = {
   spec: OasSpec,
@@ -54,6 +57,7 @@ export const rules = {
   'info-license': InfoLicense,
   'info-license-url': InfoLicenseUrl,
   'operation-2xx-response': Operation2xxResponse,
+  'operation-4xx-response': Operation4xxResponse,
   'operation-operationId-unique': OperationIdUnique,
   'operation-parameters-unique': OperationParametersUnique,
   'path-parameters-defined': PathParamsDefined,
@@ -91,6 +95,8 @@ export const rules = {
   'request-mime-type': RequestMimeType,
   'response-mime-type': ResponseMimeType,
   'path-segment-plural': PathSegmentPlural,
+  'no-invalid-schema-examples': NoInvalidSchemaExamples,
+  'no-invalid-parameter-examples': NoInvalidParameterExamples,
 } as Oas3RuleSet;
 
 export const preprocessors = {};

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

@@ -1,18 +1,25 @@
 import { Oas3Rule } from '../../visitors';
-import { validateJsonSchema } from '../ajv';
 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, { report, location, resolve }) {
+      leave(mediaType, ctx: UserContext) {
+        const { location, resolve } = ctx;
         if (!mediaType.schema) return;
-
         if (mediaType.example) {
-          validateExample(mediaType.example, location.child('example'));
+          validateExample(
+            mediaType.example,
+            mediaType.schema,
+            location.child('example'),
+            ctx,
+            disallowAdditionalProperties,
+          );
         } else if (mediaType.examples) {
           for (const exampleName of Object.keys(mediaType.examples)) {
             let example = mediaType.examples[exampleName];
@@ -23,40 +30,13 @@ export const ValidContentExamples: Oas3Rule = (opts) => {
               dataLoc = resolved.location.child('value');
               example = resolved.node;
             }
-
-            validateExample(example.value, dataLoc);
-          }
-        }
-
-        function validateExample(example: any, dataLoc: Location) {
-          try {
-            const { valid, errors } = validateJsonSchema(
-              example,
-              mediaType.schema!,
-              location.child('schema'),
-              dataLoc.pointer,
-              resolve,
+            validateExample(
+              example.value,
+              mediaType.schema,
+              dataLoc,
+              ctx,
               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/rules/oas3/no-server-trailing-slash.ts

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

package/src/rules/utils.ts

@@ -1,5 +1,8 @@
 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)) {
@@ -20,7 +23,7 @@ export function oasTypeOf(value: unknown) {
  */
 export function matchesJsonSchemaType(value: unknown, type: string, nullable: boolean): boolean {
   if (nullable && value === null) {
-    return value === null
+    return value === null;
   }
 
   switch (type) {
@@ -79,4 +82,42 @@ export function getSuggest(given: string, variants: string[]): string[] {
 
   // 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/typings/openapi.ts

@@ -150,6 +150,10 @@ export interface Oas3Schema {
   xml?: Oas3Xml;
 }
 
+export interface Oas3_1Schema extends Oas3Schema {
+  examples?: any[];
+}
+
 export interface Oas3Discriminator {
   propertyName: string;
   mapping?: { [name: string]: string };

package/src/utils.ts

@@ -159,4 +159,8 @@ export function isPathParameter(pathSegment: string) {
   }
 
   return path.replace(/\\/g, '/');
-}
+}
+
+export function isNotEmptyObject(obj: any) {
+  return !!obj && Object.keys(obj).length > 0;
+}

package/src/walk.ts

@@ -33,6 +33,7 @@ export type UserContext = {
   key: string | number;
   parent: any;
   oasVersion: OasVersion;
+  getVisitorData: () => Record<string, unknown>;
 };
 
 export type Loc = {
@@ -77,6 +78,7 @@ export type NormalizedProblem = {
 export type WalkContext = {
   problems: NormalizedProblem[];
   oasVersion: OasVersion;
+  visitorsData: Record<string, Record<string, unknown>>; // custom data store that visitors can use for various purposes
   refTypes?: Map<string, NormalizedNodeType>;
 };
 
@@ -141,6 +143,7 @@ export function walkDocument<T>(opts: {
               key,
               parentLocations: {},
               oasVersion: ctx.oasVersion,
+              getVisitorData: getVisitorDataFn.bind(undefined, ruleId)
             },
             { node: resolvedNode, location: resolvedLocation, error },
           );
@@ -325,6 +328,7 @@ export function walkDocument<T>(opts: {
               key,
               parentLocations: {},
               oasVersion: ctx.oasVersion,
+              getVisitorData: getVisitorDataFn.bind(undefined, ruleId)
             },
             { node: resolvedNode, location: resolvedLocation, error },
           );
@@ -357,6 +361,7 @@ export function walkDocument<T>(opts: {
           ignoreNextVisitorsOnNode: () => {
             ignoreNextVisitorsOnNode = true;
           },
+          getVisitorData: getVisitorDataFn.bind(undefined, ruleId),
         },
         collectParents(context),
         context,
@@ -408,5 +413,10 @@ export function walkDocument<T>(opts: {
         }),
       });
     }
+
+    function getVisitorDataFn(ruleId: string) {
+      ctx.visitorsData[ruleId] = ctx.visitorsData[ruleId] || {};
+      return ctx.visitorsData[ruleId];
+    }
   }
 }