@redocly/openapi-core 1.0.0-beta.117 → 1.0.0-beta.118

package/src/decorators/common/media-type-examples-override.ts

@@ -0,0 +1,79 @@
+import { Oas3Decorator } from '../../visitors';
+import { Oas3Operation, Oas3RequestBody, Oas3Response } from '../../typings/openapi';
+import { yamlAndJsonSyncReader } from '../../utils';
+import { isRef } from '../../ref-utils';
+import { ResolveFn, UserContext } from '../../walk';
+
+export const MediaTypeExamplesOverride: Oas3Decorator = ({ operationIds }) => {
+  return {
+    Operation: {
+      enter(operation: Oas3Operation, ctx: UserContext) {
+        const operationId = operation.operationId;
+
+        if (!operationId) {
+          return;
+        }
+
+        const properties = operationIds[operationId];
+
+        if (!properties) {
+          return;
+        }
+
+        if (properties.responses && operation.responses) {
+          for (const responseCode of Object.keys(properties.responses)) {
+            const resolvedResponse = checkAndResolveRef<Oas3Response>(
+              operation.responses[responseCode],
+              ctx.resolve
+            );
+
+            if (!resolvedResponse) {
+              continue;
+            }
+
+            resolvedResponse.content = resolvedResponse.content ? resolvedResponse.content : {};
+
+            Object.keys(properties.responses[responseCode]).forEach((mimeType) => {
+              resolvedResponse.content![mimeType] = {
+                ...resolvedResponse.content![mimeType],
+                examples: yamlAndJsonSyncReader(properties.responses[responseCode][mimeType]),
+              };
+            });
+
+            operation.responses[responseCode] = resolvedResponse;
+          }
+        }
+
+        if (properties.request && operation.requestBody) {
+          const resolvedRequest = checkAndResolveRef<Oas3RequestBody>(
+            operation.requestBody,
+            ctx.resolve
+          );
+
+          if (!resolvedRequest) {
+            return;
+          }
+
+          resolvedRequest.content = resolvedRequest.content ? resolvedRequest.content : {};
+
+          Object.keys(properties.request).forEach((mimeType) => {
+            resolvedRequest.content[mimeType] = {
+              ...resolvedRequest.content[mimeType],
+              examples: yamlAndJsonSyncReader(properties.request[mimeType]),
+            };
+          });
+          operation.requestBody = resolvedRequest;
+        }
+      },
+    },
+  };
+};
+
+function checkAndResolveRef<T>(node: any, resolver: ResolveFn): T | undefined {
+  if (!isRef(node)) {
+    return node;
+  }
+
+  const resolved = resolver<T>(node);
+  return resolved.error ? undefined : JSON.parse(JSON.stringify(resolved.node));
+}

package/src/decorators/oas3/index.ts

@@ -6,6 +6,7 @@ import { InfoDescriptionOverride } from '../common/info-description-override';
 import { RemoveXInternal } from '../common/remove-x-internal';
 import { FilterIn } from '../common/filters/filter-in';
 import { FilterOut } from '../common/filters/filter-out';
+import { MediaTypeExamplesOverride } from '../common/media-type-examples-override';
 
 export const decorators = {
   'registry-dependencies': RegistryDependencies as Oas3Decorator,
@@ -15,4 +16,5 @@ export const decorators = {
   'remove-x-internal': RemoveXInternal as Oas3Decorator,
   'filter-in': FilterIn as Oas3Decorator,
   'filter-out': FilterOut as Oas3Decorator,
+  'media-type-examples-override': MediaTypeExamplesOverride as Oas3Decorator,
 };

package/src/index.ts

@@ -36,6 +36,7 @@ export {
   CONFIG_FILE_NAMES,
   RuleSeverity,
   createConfig,
+  ResolvedApi,
 } from './config';
 
 export { RedoclyClient, isRedoclyRegistryURL } from './redocly';
@@ -50,7 +51,7 @@ export {
   makeDocumentFromString,
 } from './resolve';
 export { parseYaml, stringifyYaml } from './js-yaml';
-export { unescapePointer, isRef } from './ref-utils';
+export { unescapePointer, isRef, isAbsoluteUrl } from './ref-utils';
 export { detectOpenAPI, OasMajorVersion, openAPIMajor, OasVersion } from './oas-types';
 export { normalizeVisitors } from './visitors';
 

package/src/resolve.ts

@@ -3,7 +3,7 @@ import * as path from 'path';
 import { OasRef } from './typings/openapi';
 import { isRef, joinPointer, escapePointer, parseRef, isAbsoluteUrl, isAnchor } from './ref-utils';
 import type { YAMLNode, LoadOptions } from 'yaml-ast-parser';
-import { NormalizedNodeType, isNamedType } from './types';
+import { NormalizedNodeType, isNamedType, SpecExtension } from './types';
 import { readFileFromUrl, parseYaml, nextTick } from './utils';
 import { ResolveConfig } from './config/types';
 
@@ -276,6 +276,9 @@ export async function resolveDocument(opts: {
         if (propType === undefined) propType = type.additionalProperties;
         if (typeof propType === 'function') propType = propType(propValue, propName);
         if (propType === undefined) propType = unknownType;
+        if (type.extensionsPrefix && propName.startsWith(type.extensionsPrefix)) {
+          propType = SpecExtension;
+        }
 
         if (!isNamedType(propType) && propType?.directResolveAs) {
           propType = propType.directResolveAs;

package/src/rules/common/assertions/__tests__/asserts.test.ts

@@ -549,21 +549,25 @@ describe('oas3 assertions', () => {
       });
     });
 
-    describe.skip('sortOrder', () => {
+    describe('sortOrder', () => {
       it('value should be ordered in ASC direction', () => {
         expect(asserts.sortOrder(['example', 'foo', 'test'], 'asc', baseLocation)).toEqual([]);
         expect(
           asserts.sortOrder(['example', 'foo', 'test'], { direction: 'asc' }, baseLocation)
         ).toEqual([]);
         expect(asserts.sortOrder(['example'], 'asc', baseLocation)).toEqual([]);
-        expect(asserts.sortOrder(['example', 'test', 'foo'], 'asc', baseLocation)).toEqual({
-          isValid: false,
-          location: baseLocation,
-        });
-        expect(asserts.sortOrder(['example', 'foo', 'test'], 'desc', baseLocation)).toEqual({
-          isValid: false,
-          location: baseLocation,
-        });
+        expect(asserts.sortOrder(['example', 'test', 'foo'], 'asc', baseLocation)).toEqual([
+          {
+            message: 'Should be sorted in an ascending order',
+            location: baseLocation,
+          },
+        ]);
+        expect(asserts.sortOrder(['example', 'foo', 'test'], 'desc', baseLocation)).toEqual([
+          {
+            message: 'Should be sorted in a descending order',
+            location: baseLocation,
+          },
+        ]);
         expect(
           asserts.sortOrder(
             [{ name: 'bar' }, { name: 'baz' }, { name: 'foo' }],
@@ -577,7 +581,12 @@ describe('oas3 assertions', () => {
             { direction: 'desc', property: 'name' },
             baseLocation
           )
-        ).toEqual({ isValid: false, location: baseLocation });
+        ).toEqual([
+          {
+            message: 'Should be sorted in a descending order by property name',
+            location: baseLocation,
+          },
+        ]);
       });
       it('value should be ordered in DESC direction', () => {
         expect(asserts.sortOrder(['test', 'foo', 'example'], 'desc', baseLocation)).toEqual([]);
@@ -585,14 +594,18 @@ describe('oas3 assertions', () => {
           asserts.sortOrder(['test', 'foo', 'example'], { direction: 'desc' }, baseLocation)
         ).toEqual([]);
         expect(asserts.sortOrder(['example'], 'desc', baseLocation)).toEqual([]);
-        expect(asserts.sortOrder(['example', 'test', 'foo'], 'desc', baseLocation)).toEqual({
-          isValid: false,
-          location: baseLocation,
-        });
-        expect(asserts.sortOrder(['test', 'foo', 'example'], 'asc', baseLocation)).toEqual({
-          isValid: false,
-          location: baseLocation,
-        });
+        expect(asserts.sortOrder(['example', 'test', 'foo'], 'desc', baseLocation)).toEqual([
+          {
+            message: 'Should be sorted in a descending order',
+            location: baseLocation,
+          },
+        ]);
+        expect(asserts.sortOrder(['test', 'foo', 'example'], 'asc', baseLocation)).toEqual([
+          {
+            message: 'Should be sorted in an ascending order',
+            location: baseLocation,
+          },
+        ]);
         expect(
           asserts.sortOrder(
             [{ name: 'foo' }, { name: 'baz' }, { name: 'bar' }],
@@ -606,7 +619,64 @@ describe('oas3 assertions', () => {
             { direction: 'asc', property: 'name' },
             baseLocation
           )
-        ).toEqual({ isValid: false, location: baseLocation });
+        ).toEqual([
+          {
+            message: 'Should be sorted in an ascending order by property name',
+            location: baseLocation,
+          },
+        ]);
+      });
+      it('should not order objects without property defined', () => {
+        expect(
+          asserts.sortOrder(
+            [
+              { name: 'bar', id: 1 },
+              { name: 'baz', id: 2 },
+              { name: 'foo', id: 3 },
+            ],
+            { direction: 'desc' },
+            baseLocation
+          )
+        ).toEqual([
+          {
+            message: 'Please define a property to sort objects by',
+            location: baseLocation,
+          },
+        ]);
+        expect(
+          asserts.sortOrder(
+            [
+              { name: 'bar', id: 1 },
+              { name: 'baz', id: 2 },
+              { name: 'foo', id: 3 },
+            ],
+            { direction: 'asc' },
+            baseLocation
+          )
+        ).toEqual([
+          {
+            message: 'Please define a property to sort objects by',
+            location: baseLocation,
+          },
+        ]);
+      });
+      it('should ignore string value casing while ordering', () => {
+        expect(asserts.sortOrder(['Example', 'foo', 'Test'], 'asc', baseLocation)).toEqual([]);
+        expect(asserts.sortOrder(['Test', 'foo', 'Example'], 'desc', baseLocation)).toEqual([]);
+        expect(
+          asserts.sortOrder(
+            [{ name: 'bar' }, { name: 'Baz' }, { name: 'Foo' }],
+            { direction: 'asc', property: 'name' },
+            baseLocation
+          )
+        ).toEqual([]);
+        expect(
+          asserts.sortOrder(
+            [{ name: 'Foo' }, { name: 'baz' }, { name: 'Bar' }],
+            { direction: 'desc', property: 'name' },
+            baseLocation
+          )
+        ).toEqual([]);
       });
     });
 

package/src/rules/common/assertions/asserts.ts

@@ -239,9 +239,18 @@ export const asserts: Asserts = {
     condition: OrderOptions | OrderDirection,
     baseLocation: Location
   ) => {
-    if (typeof value === 'undefined' || isOrdered(value, condition)) return [];
     const direction = (condition as OrderOptions).direction || (condition as OrderDirection);
     const property = (condition as OrderOptions).property;
+    if (Array.isArray(value) && value.length > 0 && typeof value[0] === 'object' && !property) {
+      return [
+        {
+          message: `Please define a property to sort objects by`,
+          location: baseLocation,
+        },
+      ];
+    }
+    if (typeof value === 'undefined' || isOrdered(value, condition)) return [];
+
     return [
       {
         message: `Should be sorted in ${

package/src/rules/common/assertions/utils.ts

@@ -118,11 +118,11 @@ function applyAssertions(
         );
       }
     } else {
-      const value = assert.name === 'ref' ? rawNode : Object.keys(node);
+      const value = Array.isArray(node) ? node : Object.keys(node);
       assertResults.push(
         runAssertion({
-          values: Object.keys(node),
-          rawValues: value,
+          values: value,
+          rawValues: rawNode,
           assert,
           location: currentLocation,
         })
@@ -288,11 +288,20 @@ export function isOrdered(value: any[], options: OrderOptions | OrderDirection):
     let prevVal = value[i - 1];
 
     if (property) {
-      if (!value[i][property] || !value[i - 1][property]) {
+      const currPropValue = value[i][property];
+      const prevPropValue = value[i - 1][property];
+
+      if (!currPropValue || !prevPropValue) {
         return false; // property doesn't exist, so collection is not ordered
       }
-      currValue = value[i][property];
-      prevVal = value[i - 1][property];
+
+      currValue = currPropValue;
+      prevVal = prevPropValue;
+    }
+
+    if (typeof currValue === 'string' && typeof prevVal === 'string') {
+      currValue = currValue.toLowerCase();
+      prevVal = prevVal.toLowerCase();
     }
 
     const result = direction === 'asc' ? currValue >= prevVal : currValue <= prevVal;

package/src/rules/common/spec.ts

@@ -1,5 +1,5 @@
 import type { Oas3Rule, Oas2Rule } from '../../visitors';
-import { isNamedType } from '../../types';
+import { isNamedType, SpecExtension } from '../../types';
 import { oasTypeOf, matchesJsonSchemaType, getSuggest, validateSchemaEnumType } from '../utils';
 import { isRef } from '../../ref-utils';
 import { isPlainObject } from '../../utils';
@@ -24,10 +24,13 @@ export const OasSpec: Oas3Rule | Oas2Rule = () => {
         }
         return;
       } else if (nodeType !== 'object') {
-        report({
-          message: `Expected type \`${type.name}\` (object) but got \`${nodeType}\``,
-          from: refLocation,
-        });
+        if (type !== SpecExtension) {
+          // do not validate unknown extensions structure
+          report({
+            message: `Expected type \`${type.name}\` (object) but got \`${nodeType}\``,
+            from: refLocation,
+          });
+        }
         ignoreNextVisitorsOnNode();
         return;
       }

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

@@ -214,4 +214,92 @@ describe('Oas3 spec-components-invalid-map-name', () => {
 
     expect(results).toMatchInlineSnapshot(`Array []`);
   });
+
+  it('should report about invalid keys inside nested examples', async () => {
+    const document = parseYamlToDocument(outdent`
+      openapi: 3.0.0
+      info:
+        version: 3.0.0
+      components:
+        parameters:
+          my Param:
+            name: param
+            description: param
+            in: path
+            examples:
+              invalid identifier:
+                description: 'Some description'
+                value: 21 
+		`);
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'spec-components-invalid-map-name': 'error',
+      }),
+    });
+
+    expect(results).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/components/parameters/my Param",
+              "reportOnKey": true,
+              "source": Source {
+                "absoluteRef": "",
+                "body": "openapi: 3.0.0
+      info:
+        version: 3.0.0
+      components:
+        parameters:
+          my Param:
+            name: param
+            description: param
+            in: path
+            examples:
+              invalid identifier:
+                description: 'Some description'
+                value: 21 ",
+                "mimeType": undefined,
+              },
+            },
+          ],
+          "message": "The map key in parameters \\"my Param\\" does not match the regular expression \\"^[a-zA-Z0-9\\\\.\\\\-_]+$\\"",
+          "ruleId": "spec-components-invalid-map-name",
+          "severity": "error",
+          "suggest": Array [],
+        },
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/components/parameters/my Param/examples/invalid identifier",
+              "reportOnKey": true,
+              "source": Source {
+                "absoluteRef": "",
+                "body": "openapi: 3.0.0
+      info:
+        version: 3.0.0
+      components:
+        parameters:
+          my Param:
+            name: param
+            description: param
+            in: path
+            examples:
+              invalid identifier:
+                description: 'Some description'
+                value: 21 ",
+                "mimeType": undefined,
+              },
+            },
+          ],
+          "message": "The map key in examples \\"invalid identifier\\" does not match the regular expression \\"^[a-zA-Z0-9\\\\.\\\\-_]+$\\"",
+          "ruleId": "spec-components-invalid-map-name",
+          "severity": "error",
+          "suggest": Array [],
+        },
+      ]
+    `);
+  });
 });

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

@@ -20,34 +20,55 @@ export const SpecComponentsInvalidMapName: Oas3Rule = () => {
   }
 
   return {
-    Components: {
+    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');
       },
-      Schema(_node, { key, report, location }: UserContext) {
-        validateKey(key, report, location, 'schemas');
-      },
+    },
+    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, 'securitySchemas');
+        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');
       },
     },
+    ExampleMap: {
+      Example(_node, { key, report, location }: UserContext) {
+        validateKey(key, report, location, 'examples');
+      },
+    },
   };
 };

package/src/types/index.ts

@@ -63,6 +63,11 @@ export function mapOf(typeName: string) {
   };
 }
 
+export const SpecExtension: NormalizedNodeType = {
+  name: 'SpecExtension',
+  properties: {},
+};
+
 export function normalizeTypes(
   types: Record<string, NodeType>,
   options: { doNotResolveExamples?: boolean } = {}
@@ -79,6 +84,10 @@ export function normalizeTypes(
   for (const type of Object.values(normalizedTypes)) {
     normalizeType(type);
   }
+
+  // all type trees have a SpecExtension type by default
+  normalizedTypes['SpecExtension'] = SpecExtension;
+
   return normalizedTypes;
 
   function normalizeType(type: NormalizedNodeType) {

package/src/types/oas2.ts

@@ -24,6 +24,7 @@ const Root: NodeType = {
     'x-ignoredHeaderParameters': { type: 'array', items: { type: 'string' } },
   },
   required: ['swagger', 'paths', 'info'],
+  extensionsPrefix: 'x-',
 };
 
 const Info: NodeType = {
@@ -37,6 +38,7 @@ const Info: NodeType = {
     'x-logo': 'Logo',
   },
   required: ['title', 'version'],
+  extensionsPrefix: 'x-',
 };
 
 const Logo: NodeType = {
@@ -46,6 +48,7 @@ const Logo: NodeType = {
     backgroundColor: { type: 'string' },
     href: { type: 'string' },
   },
+  extensionsPrefix: 'x-',
 };
 
 const Contact: NodeType = {
@@ -54,6 +57,7 @@ const Contact: NodeType = {
     url: { type: 'string' },
     email: { type: 'string' },
   },
+  extensionsPrefix: 'x-',
 };
 
 const License: NodeType = {
@@ -62,6 +66,7 @@ const License: NodeType = {
     url: { type: 'string' },
   },
   required: ['name'],
+  extensionsPrefix: 'x-',
 };
 
 const Paths: NodeType = {
@@ -83,6 +88,7 @@ const PathItem: NodeType = {
     head: 'Operation',
     patch: 'Operation',
   },
+  extensionsPrefix: 'x-',
 };
 
 const Operation: NodeType = {
@@ -104,6 +110,7 @@ const Operation: NodeType = {
     'x-hideTryItPanel': { type: 'boolean' },
   },
   required: ['responses'],
+  extensionsPrefix: 'x-',
 };
 
 const XCodeSample: NodeType = {
@@ -128,6 +135,7 @@ const ExternalDocs: NodeType = {
     url: { type: 'string' },
   },
   required: ['url'],
+  extensionsPrefix: 'x-',
 };
 
 const Parameter: NodeType = {
@@ -172,6 +180,7 @@ const Parameter: NodeType = {
       }
     }
   },
+  extensionsPrefix: 'x-',
 };
 
 const ParameterItems: NodeType = {
@@ -201,6 +210,7 @@ const ParameterItems: NodeType = {
       return ['type'];
     }
   },
+  extensionsPrefix: 'x-',
 };
 
 const Responses: NodeType = {
@@ -220,6 +230,7 @@ const Response: NodeType = {
     'x-summary': { type: 'string' },
   },
   required: ['description'],
+  extensionsPrefix: 'x-',
 };
 
 const Examples: NodeType = {
@@ -255,6 +266,7 @@ const Header: NodeType = {
       return ['type'];
     }
   },
+  extensionsPrefix: 'x-',
 };
 
 const Tag: NodeType = {
@@ -266,6 +278,7 @@ const Tag: NodeType = {
     'x-displayName': { type: 'string' },
   },
   required: ['name'],
+  extensionsPrefix: 'x-',
 };
 
 const TagGroup: NodeType = {
@@ -328,6 +341,7 @@ const Schema: NodeType = {
     'x-explicitMappingOnly': { type: 'boolean' },
     'x-enumDescriptions': 'EnumDescriptions',
   },
+  extensionsPrefix: 'x-',
 };
 
 const EnumDescriptions: NodeType = {
@@ -348,6 +362,7 @@ const Xml: NodeType = {
     attribute: { type: 'boolean' },
     wrapped: { type: 'boolean' },
   },
+  extensionsPrefix: 'x-',
 };
 
 const SecurityScheme: NodeType = {
@@ -419,6 +434,7 @@ const Example: NodeType = {
     description: { type: 'string' },
     externalValue: { type: 'string' },
   },
+  extensionsPrefix: 'x-',
 };
 
 export const Oas2Types: Record<string, NodeType> = {