@redocly/openapi-core 1.13.0 → 1.15.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @redocly/openapi-core
 
+## 1.15.0
+
+### Minor Changes
+
+- Made `redocly.yaml` validation consistent with the general Redocly config.
+
+### Patch Changes
+
+- Fixed `no-invalid-media-type-examples`, `no-invalid-parameter-examples`, and `no-invalid-schema-examples` rules which allowed falsy example values to pass for any schema.
+
+## 1.14.0
+
+### Minor Changes
+
+- Added the ability to exclude some operations or entire paths from the `security-defined` rule.
+
 ## 1.13.0
 
 ### Minor Changes

package/lib/rules/common/no-invalid-parameter-examples.js

@@ -8,7 +8,7 @@ const NoInvalidParameterExamples = (opts) => {
     return {
         Parameter: {
             leave(parameter, ctx) {
-                if (parameter.example) {
+                if (parameter.example !== undefined) {
                     (0, utils_1.validateExample)(parameter.example, parameter.schema, ctx.location.child('example'), ctx, allowAdditionalProperties);
                 }
                 if (parameter.examples) {

package/lib/rules/common/no-invalid-schema-examples.js

@@ -13,7 +13,7 @@ const NoInvalidSchemaExamples = (opts) => {
                         (0, utils_1.validateExample)(example, schema, ctx.location.child(['examples', schema.examples.indexOf(example)]), ctx, allowAdditionalProperties);
                     }
                 }
-                if (schema.example) {
+                if (schema.example !== undefined) {
                     (0, utils_1.validateExample)(schema.example, schema, ctx.location.child('example'), ctx, true);
                 }
             },

package/lib/rules/common/security-defined.js

@@ -1,10 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SecurityDefined = void 0;
-const SecurityDefined = () => {
+const SecurityDefined = (opts) => {
     const referencedSchemes = new Map();
     const operationsWithoutSecurity = [];
     let eachOperationHasSecurity = true;
+    let path;
     return {
         Root: {
             leave(root, { report }) {
@@ -46,11 +47,22 @@ const SecurityDefined = () => {
                 }
             }
         },
-        Operation(operation, { location }) {
-            if (!(operation === null || operation === void 0 ? void 0 : operation.security)) {
-                eachOperationHasSecurity = false;
-                operationsWithoutSecurity.push(location);
-            }
+        PathItem: {
+            enter(pathItem, { key }) {
+                path = key;
+            },
+            Operation(operation, { location, key }) {
+                var _a;
+                const isException = (_a = opts.exceptions) === null || _a === void 0 ? void 0 : _a.some((item) => {
+                    var _a;
+                    return item.path === path &&
+                        (!item.methods || ((_a = item.methods) === null || _a === void 0 ? void 0 : _a.some((method) => method.toLowerCase() === key)));
+                });
+                if (!(operation === null || operation === void 0 ? void 0 : operation.security) && !isException) {
+                    eachOperationHasSecurity = false;
+                    operationsWithoutSecurity.push(location);
+                }
+            },
         },
     };
 };

package/lib/rules/oas3/no-invalid-media-type-examples.js

@@ -12,7 +12,7 @@ const ValidContentExamples = (opts) => {
                 const { location, resolve } = ctx;
                 if (!mediaType.schema)
                     return;
-                if (mediaType.example) {
+                if (mediaType.example !== undefined) {
                     resolveAndValidateExample(mediaType.example, location.child('example'));
                 }
                 else if (mediaType.examples) {

package/lib/types/redocly-yaml.d.ts

@@ -19,7 +19,6 @@ export type Oas3_1NodeType = typeof oas3_1NodeTypesList[number];
 export declare const createConfigTypes: (extraSchemas: JSONSchema) => {
     ConfigRoot: NodeType;
     ConfigApisProperties: NodeType;
-    ConfigRootTheme: NodeType;
 };
 export declare const ConfigTypes: Record<string, NodeType>;
 export {};

package/lib/types/redocly-yaml.js

@@ -220,7 +220,7 @@ const ConfigStyleguide = {
         async2Decorators: { type: 'object' },
     },
 };
-const createConfigRoot = (nodeTypes) => (Object.assign(Object.assign({}, nodeTypes.rootRedoclyConfigSchema), { properties: Object.assign(Object.assign(Object.assign({}, nodeTypes.rootRedoclyConfigSchema.properties), ConfigStyleguide.properties), { apis: 'ConfigApis', theme: 'ConfigRootTheme', 'features.openapi': 'ConfigReferenceDocs', 'features.mockServer': 'ConfigMockServer', organization: { type: 'string' }, region: { enum: ['us', 'eu'] }, telemetry: { enum: ['on', 'off'] }, resolve: {
+const createConfigRoot = (nodeTypes) => (Object.assign(Object.assign({}, nodeTypes.rootRedoclyConfigSchema), { properties: Object.assign(Object.assign(Object.assign({}, nodeTypes.rootRedoclyConfigSchema.properties), ConfigStyleguide.properties), { apis: 'ConfigApis', 'features.openapi': 'ConfigReferenceDocs', 'features.mockServer': 'ConfigMockServer', organization: { type: 'string' }, region: { enum: ['us', 'eu'] }, telemetry: { enum: ['on', 'off'] }, resolve: {
             properties: {
                 http: 'ConfigHTTP',
                 doNotResolveExamples: { type: 'boolean' },
@@ -259,10 +259,6 @@ const ConfigHTTP = {
         },
     },
 };
-const createConfigRootTheme = (nodeTypes) => {
-    var _a;
-    return (Object.assign(Object.assign({}, nodeTypes['rootRedoclyConfigSchema.theme']), { properties: Object.assign(Object.assign({}, (_a = nodeTypes['rootRedoclyConfigSchema.theme']) === null || _a === void 0 ? void 0 : _a.properties), { openapi: 'ConfigReferenceDocs' }) }));
-};
 const Rules = {
     properties: {},
     additionalProperties: (value, key) => {
@@ -765,8 +761,8 @@ const GenerateCodeSamples = {
     },
     required: ['languages'],
 };
+// TODO: deprecated
 const ConfigReferenceDocs = {
-    // TODO: partially invalid @Viacheslav
     properties: {
         theme: 'ConfigTheme',
         corsProxyUrl: { type: 'string' },
@@ -904,7 +900,7 @@ const ConfigMockServer = {
 const createConfigTypes = (extraSchemas) => {
     // Create types based on external schemas
     const nodeTypes = (0, json_schema_adapter_1.getNodeTypesFromJSONSchema)('rootRedoclyConfigSchema', extraSchemas);
-    return Object.assign(Object.assign(Object.assign({}, CoreConfigTypes), { ConfigRoot: createConfigRoot(nodeTypes), ConfigApisProperties: createConfigApisProperties(nodeTypes), ConfigRootTheme: createConfigRootTheme(nodeTypes) }), nodeTypes);
+    return Object.assign(Object.assign(Object.assign({}, CoreConfigTypes), { ConfigRoot: createConfigRoot(nodeTypes), ConfigApisProperties: createConfigApisProperties(nodeTypes) }), nodeTypes);
 };
 exports.createConfigTypes = createConfigTypes;
 const CoreConfigTypes = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redocly/openapi-core",
-  "version": "1.13.0",
+  "version": "1.15.0",
   "description": "",
   "main": "lib/index.js",
   "engines": {
@@ -35,7 +35,7 @@
   ],
   "dependencies": {
     "@redocly/ajv": "^8.11.0",
-    "@redocly/config": "^0.5.0",
+    "@redocly/config": "^0.6.0",
     "colorette": "^1.2.0",
     "js-levenshtein": "^1.1.6",
     "js-yaml": "^4.1.0",

package/src/__tests__/lint.test.ts

@@ -369,26 +369,8 @@ describe('lint', () => {
                 min: 3
         theme:
           openapi:
-            showConsole: true
-            layout:
-              scope: section
-            routingStrategy: browser
-            theme:
-              rightPanel:
-                backgroundColor: '#263238'
-              links:
-                color: '#6CC496'
-              theme:
-                openapi:
-                  showConsole: true
-                  layout:
-                    scope: section
-                  routingStrategy: browser
-                  theme:
-                    rightPanel:
-                      backgroundColor: '#263238'
-                    links:
-                      color: '#6CC496'
+            showConsole: true # Not expected anymore
+            layout: wrong-option
       `,
       ''
     );
@@ -414,12 +396,12 @@ describe('lint', () => {
           "from": undefined,
           "location": [
             {
-              "pointer": "#/theme/openapi/layout",
-              "reportOnKey": false,
+              "pointer": "#/theme/openapi/showConsole",
+              "reportOnKey": true,
               "source": "",
             },
           ],
-          "message": "\`layout\` can be one of the following only: "stacked", "three-panel".",
+          "message": "Property \`showConsole\` is not expected here.",
           "ruleId": "configuration spec",
           "severity": "error",
           "suggest": [],
@@ -428,18 +410,15 @@ describe('lint', () => {
           "from": undefined,
           "location": [
             {
-              "pointer": "#/theme/openapi/theme/theme",
-              "reportOnKey": true,
+              "pointer": "#/theme/openapi/layout",
+              "reportOnKey": false,
               "source": "",
             },
           ],
-          "message": "Property \`theme\` is not expected here.",
+          "message": "\`layout\` can be one of the following only: "stacked", "three-panel".",
           "ruleId": "configuration spec",
           "severity": "error",
-          "suggest": [
-            "schema",
-            "shape",
-          ],
+          "suggest": [],
         },
       ]
     `);
@@ -806,12 +785,12 @@ describe('lint', () => {
           "from": undefined,
           "location": [
             {
-              "pointer": "#/apis/with-theme/theme/openapi",
-              "reportOnKey": false,
+              "pointer": "#/apis/with-theme/theme/not-expected",
+              "reportOnKey": true,
               "source": "",
             },
           ],
-          "message": "Expected type \`object\` but got \`string\`.",
+          "message": "Property \`not-expected\` is not expected here.",
           "ruleId": "configuration spec",
           "severity": "error",
           "suggest": [],
@@ -820,12 +799,12 @@ describe('lint', () => {
           "from": undefined,
           "location": [
             {
-              "pointer": "#/apis/with-theme/theme/not-expected",
-              "reportOnKey": true,
+              "pointer": "#/apis/with-theme/theme/openapi",
+              "reportOnKey": false,
               "source": "",
             },
           ],
-          "message": "Property \`not-expected\` is not expected here.",
+          "message": "Expected type \`rootRedoclyConfigSchema.apis_additionalProperties.theme.openapi\` (object) but got \`string\`",
           "ruleId": "configuration spec",
           "severity": "error",
           "suggest": [],

package/src/config/__tests__/load.test.ts

@@ -149,19 +149,6 @@ describe('getConfig', () => {
           "severity": "warn",
           "suggest": [],
         },
-        {
-          "location": [
-            {
-              "pointer": "#/theme",
-              "reportOnKey": false,
-              "source": "fixtures/resolve-refs-in-config/config-with-refs.yaml",
-            },
-          ],
-          "message": "Can't resolve $ref: ENOENT: no such file or directory 'fixtures/resolve-refs-in-config/wrong-ref.yaml'",
-          "ruleId": "configuration no-unresolved-refs",
-          "severity": "warn",
-          "suggest": [],
-        },
         {
           "from": {
             "pointer": "#/rules",
@@ -179,6 +166,19 @@ describe('getConfig', () => {
           "severity": "warn",
           "suggest": [],
         },
+        {
+          "location": [
+            {
+              "pointer": "#/theme",
+              "reportOnKey": false,
+              "source": "fixtures/resolve-refs-in-config/config-with-refs.yaml",
+            },
+          ],
+          "message": "Can't resolve $ref: ENOENT: no such file or directory 'fixtures/resolve-refs-in-config/wrong-ref.yaml'",
+          "ruleId": "configuration no-unresolved-refs",
+          "severity": "warn",
+          "suggest": [],
+        },
       ]
     `);
   });

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

@@ -0,0 +1,53 @@
+import { outdent } from 'outdent';
+import { lintDocument } from '../../../lint';
+import { parseYamlToDocument, replaceSourceWithRef, makeConfig } from '../../../../__tests__/utils';
+import { BaseResolver } from '../../../resolve';
+
+describe('no-invalid-parameter-examples', () => {
+  it('should report on invalid falsy example', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.1.0
+        paths:
+          /results:
+            get:
+              parameters:
+                - name: username
+                  in: query
+                  schema:
+                    type: string
+                    maxLength: 15
+                  example: false
+      `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'no-invalid-parameter-examples': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      [
+        {
+          "from": {
+            "pointer": "#/paths/~1results/get/parameters/0",
+            "source": "foobar.yaml",
+          },
+          "location": [
+            {
+              "pointer": "#/paths/~1results/get/parameters/0/example",
+              "reportOnKey": false,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Example value must conform to the schema: type must be string.",
+          "ruleId": "no-invalid-parameter-examples",
+          "severity": "error",
+          "suggest": [],
+        },
+      ]
+    `);
+  });
+});

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

@@ -0,0 +1,51 @@
+import { outdent } from 'outdent';
+import { lintDocument } from '../../../lint';
+import { parseYamlToDocument, replaceSourceWithRef, makeConfig } from '../../../../__tests__/utils';
+import { BaseResolver } from '../../../resolve';
+
+describe('no-invalid-schema-examples', () => {
+  it('should report on invalid falsy example', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.1.0
+        components:
+          schemas:
+            Car:
+              type: object
+              properties:
+                color:
+                  type: string
+                  example: 0
+      `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'no-invalid-schema-examples': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      [
+        {
+          "from": {
+            "pointer": "#/components/schemas/Car/properties/color",
+            "source": "foobar.yaml",
+          },
+          "location": [
+            {
+              "pointer": "#/components/schemas/Car/properties/color/example",
+              "reportOnKey": false,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Example value must conform to the schema: type must be string.",
+          "ruleId": "no-invalid-schema-examples",
+          "severity": "error",
+          "suggest": [],
+        },
+      ]
+    `);
+  });
+});

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

@@ -172,4 +172,107 @@ describe('Oas3 security-defined', () => {
 
     expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`[]`);
   });
+
+  it('should not report if a pathItem is explicitly excluded in the option', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+      openapi: 3.1.0
+      paths:
+        /excluded:
+          get:
+            description: Should be skipped.
+          post: 
+            description: Should be skipped.`,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'security-defined': { exceptions: [{ path: '/excluded' }] },
+      }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`[]`);
+  });
+
+  it('should report only those operations without security defined that are not excluded in the options', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+      openapi: 3.1.0
+      paths:
+        /partially-excluded:
+          get:
+            description: Should be skipped.
+          post: 
+            description: Has security.
+            security: []
+          delete: 
+            description: Should have security defined.`,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'security-defined': { exceptions: [{ path: '/partially-excluded', methods: ['GET'] }] },
+      }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      [
+        {
+          "location": [
+            {
+              "pointer": "#/paths/~1partially-excluded/delete",
+              "reportOnKey": true,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Every operation should have security defined on it or on the root level.",
+          "ruleId": "security-defined",
+          "severity": "error",
+          "suggest": [],
+        },
+      ]
+    `);
+  });
+
+  it('should report operations from path items that are not excluded', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+      openapi: 3.1.0
+      paths:
+        /not-excluded:
+          get: 
+            summary: Should have security defined.`,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'security-defined': { exceptions: [{ path: '/excluded' }] } }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      [
+        {
+          "location": [
+            {
+              "pointer": "#/paths/~1not-excluded/get",
+              "reportOnKey": true,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Every operation should have security defined on it or on the root level.",
+          "ruleId": "security-defined",
+          "severity": "error",
+          "suggest": [],
+        },
+      ]
+    `);
+  });
 });

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

@@ -7,7 +7,7 @@ export const NoInvalidParameterExamples: any = (opts: any) => {
   return {
     Parameter: {
       leave(parameter: Oas3Parameter, ctx: UserContext) {
-        if (parameter.example) {
+        if (parameter.example !== undefined) {
           validateExample(
             parameter.example,
             parameter.schema!,

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

@@ -18,7 +18,7 @@ export const NoInvalidSchemaExamples: any = (opts: any) => {
             );
           }
         }
-        if (schema.example) {
+        if (schema.example !== undefined) {
           validateExample(schema.example, schema, ctx.location.child('example'), ctx, true);
         }
       },

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

@@ -1,10 +1,22 @@
 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';
+import {
+  Oas2Definition,
+  Oas2Operation,
+  Oas2PathItem,
+  Oas2SecurityScheme,
+} from '../../typings/swagger';
+import {
+  Oas3Definition,
+  Oas3Operation,
+  Oas3PathItem,
+  Oas3SecurityScheme,
+} from '../../typings/openapi';
 
-export const SecurityDefined: Oas3Rule | Oas2Rule = () => {
+export const SecurityDefined: Oas3Rule | Oas2Rule = (opts: {
+  exceptions?: { path: string; methods?: string[] }[];
+}) => {
   const referencedSchemes = new Map<
     string,
     {
@@ -15,6 +27,7 @@ export const SecurityDefined: Oas3Rule | Oas2Rule = () => {
 
   const operationsWithoutSecurity: Location[] = [];
   let eachOperationHasSecurity: boolean = true;
+  let path: string | undefined;
 
   return {
     Root: {
@@ -55,11 +68,21 @@ export const SecurityDefined: Oas3Rule | Oas2Rule = () => {
         }
       }
     },
-    Operation(operation: Oas2Operation | Oas3Operation, { location }: UserContext) {
-      if (!operation?.security) {
-        eachOperationHasSecurity = false;
-        operationsWithoutSecurity.push(location);
-      }
+    PathItem: {
+      enter(pathItem: Oas2PathItem | Oas3PathItem, { key }: UserContext) {
+        path = key as string;
+      },
+      Operation(operation: Oas2Operation | Oas3Operation, { location, key }: UserContext) {
+        const isException = opts.exceptions?.some(
+          (item) =>
+            item.path === path &&
+            (!item.methods || item.methods?.some((method) => method.toLowerCase() === key))
+        );
+        if (!operation?.security && !isException) {
+          eachOperationHasSecurity = false;
+          operationsWithoutSecurity.push(location);
+        }
+      },
     },
   };
 };

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

@@ -137,6 +137,58 @@ describe('no-invalid-media-type-examples', () => {
     `);
   });
 
+  it('should report on invalid example with a falsy value', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.1.0
+        paths:
+          /test:
+            get:
+              responses:
+                '200':
+                  content:
+                    application/json:
+                      schema:
+                        type: string
+                      example: false
+      `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'no-invalid-media-type-examples': {
+          severity: 'error',
+          allowAdditionalProperties: false,
+        },
+      }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      [
+        {
+          "from": {
+            "pointer": "#/paths/~1test/get/responses/200/content/application~1json",
+            "source": "foobar.yaml",
+          },
+          "location": [
+            {
+              "pointer": "#/paths/~1test/get/responses/200/content/application~1json/example",
+              "reportOnKey": false,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Example value must conform to the schema: type must be string.",
+          "ruleId": "no-invalid-media-type-examples",
+          "severity": "error",
+          "suggest": [],
+        },
+      ]
+    `);
+  });
+
   it('should not report on valid example with allowAdditionalProperties', async () => {
     const document = parseYamlToDocument(
       outdent`

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

@@ -12,7 +12,7 @@ export const ValidContentExamples: Oas3Rule = (opts) => {
       leave(mediaType, ctx: UserContext) {
         const { location, resolve } = ctx;
         if (!mediaType.schema) return;
-        if (mediaType.example) {
+        if (mediaType.example !== undefined) {
           resolveAndValidateExample(mediaType.example, location.child('example'));
         } else if (mediaType.examples) {
           for (const exampleName of Object.keys(mediaType.examples)) {