@redocly/openapi-core 1.0.0-beta.98 → 1.0.0-beta.99

package/src/__tests__/lint.test.ts

@@ -4,6 +4,7 @@ import { lintFromString, lintConfig, lintDocument } from '../lint';
 import { BaseResolver } from '../resolve';
 import { loadConfig } from '../config/load';
 import { parseYamlToDocument, replaceSourceWithRef, makeConfig } from '../../__tests__/utils';
+import { detectOpenAPI } from '../oas-types';
 
 describe('lint', () => {
   it('lintFromString should work', async () => {
@@ -179,4 +180,16 @@ describe('lint', () => {
 
     expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`Array []`);
   });
+
+  it('detect OpenAPI should throw an error when version is not string', () => {
+    const testDocument = parseYamlToDocument(
+      outdent`
+      openapi: 3.0
+    `,
+      '',
+    );
+    expect(() => detectOpenAPI(testDocument.parsed)).toThrow(
+      `Invalid OpenAPI version: should be a string but got "number"`,
+    );
+  });
 });

package/{__tests__ → src/__tests__}/login.test.ts

@@ -1,4 +1,4 @@
-import { RedoclyClient } from '../src/redocly';
+import { RedoclyClient } from '../redocly';
 
 describe.skip('login', () => {
   it('should call login with setAccessTokens function', async () => {

package/{__tests__ → src/__tests__}/normalizeVisitors.test.ts

@@ -1,7 +1,7 @@
-import { normalizeVisitors, VisitorLevelContext } from '../src/visitors';
-import { Oas3RuleSet } from '../src/oas-types';
-import { Oas3Types } from '../src/types/oas3';
-import { normalizeTypes } from '../src/types';
+import { normalizeVisitors, VisitorLevelContext } from '../visitors';
+import { Oas3RuleSet } from '../oas-types';
+import { Oas3Types } from '../types/oas3';
+import { normalizeTypes } from '../types';
 
 describe('Normalize visitors', () => {
   it('should work correctly for single rule', () => {

package/{__tests__ → src/__tests__}/ref-utils.test.ts

@@ -1,9 +1,9 @@
 import outdent from 'outdent';
-import { parseYamlToDocument } from './utils';
-import { parseRef, refBaseName } from '../src/ref-utils';
-import { lintDocument } from '../src/lint';
-import { LintConfig } from '../src/config';
-import { BaseResolver } from '../src/resolve';
+import { parseYamlToDocument } from '../../__tests__/utils';
+import { parseRef, refBaseName } from '../ref-utils';
+import { lintDocument } from '../lint';
+import { LintConfig } from '../config';
+import { BaseResolver } from '../resolve';
 
 describe('ref-utils', () => {
   it(`should unescape refs with '/'`, () => {

package/{__tests__ → src/__tests__}/resolve-http.test.ts

@@ -1,9 +1,9 @@
 import { outdent } from 'outdent';
 
-import { resolveDocument, BaseResolver } from '../src/resolve';
-import { parseYamlToDocument } from './utils';
-import { Oas3Types } from '../src/types/oas3';
-import { normalizeTypes } from '../src/types';
+import { resolveDocument, BaseResolver } from '../resolve';
+import { parseYamlToDocument } from '../../__tests__/utils';
+import { Oas3Types } from '../types/oas3';
+import { normalizeTypes } from '../types';
 
 describe('Resolve http-headers', () => {
   it('should use matching http-headers', async () => {

package/{__tests__ → src/__tests__}/resolve.test.ts

@@ -1,10 +1,10 @@
 import { outdent } from 'outdent';
 import * as path from 'path';
 
-import { resolveDocument, BaseResolver, Document } from '../src/resolve';
-import { parseYamlToDocument } from './utils';
-import { Oas3Types } from '../src/types/oas3';
-import { normalizeTypes } from '../src/types';
+import { resolveDocument, BaseResolver, Document } from '../resolve';
+import { parseYamlToDocument } from '../../__tests__/utils';
+import { Oas3Types } from '../types/oas3';
+import { normalizeTypes } from '../types';
 
 describe('collect refs', () => {
   it('should resolve local refs', async () => {

package/src/__tests__/utils.test.ts

@@ -1,4 +1,4 @@
-import { pickObjectProps, omitObjectProps, slash } from '../utils';
+import { pickObjectProps, omitObjectProps, slash, getMatchingStatusCodeRange } from '../utils';
 
 describe('utils', () => {
   const testObject = {
@@ -71,4 +71,15 @@ describe('utils', () => {
       expect(slash(extended)).toBe(extended);
     });
   });
+
+  describe('getMatchingStatusCodeRange', () => {
+    it('should get the generalized form of status codes', () => {
+      expect(getMatchingStatusCodeRange('202')).toEqual('2XX');
+      expect(getMatchingStatusCodeRange(400)).toEqual('4XX');
+    });
+    it('should fail on a wrong input', () => {
+      expect(getMatchingStatusCodeRange('2002')).toEqual('2002');
+      expect(getMatchingStatusCodeRange(4000)).toEqual('4000');
+    });
+  });
 });

package/{__tests__ → src/__tests__}/walk.test.ts

@@ -2,12 +2,12 @@ import outdent from 'outdent';
 import each from 'jest-each';
 import * as path from 'path';
 
-import { lintDocument } from '../src/lint';
+import { lintDocument } from '../lint';
 
-import { parseYamlToDocument, replaceSourceWithRef, makeConfigForRuleset } from './utils';
-import { BaseResolver, Document } from '../src/resolve';
-import { listOf } from '../src/types';
-import { Oas3RuleSet } from '../src/oas-types';
+import { parseYamlToDocument, replaceSourceWithRef, makeConfigForRuleset } from '../../__tests__/utils';
+import { BaseResolver, Document } from '../resolve';
+import { listOf } from '../types';
+import { Oas3RuleSet } from '../oas-types';
 
 describe('walk order', () => {
   it('should run visitors', async () => {

package/src/bundle.ts

@@ -7,7 +7,7 @@ import { Oas3_1Types } from './types/oas3_1';
 import { NormalizedNodeType, normalizeTypes, NodeType } from './types';
 import { WalkContext, walkDocument, UserContext, ResolveResult } from './walk';
 import { detectOpenAPI, openAPIMajor, OasMajorVersion } from './oas-types';
-import { isRef, Location, refBaseName } from './ref-utils';
+import {isAbsoluteUrl, isRef, Location, refBaseName} from './ref-utils';
 import { initRules } from './config/rules';
 import { reportUnresolvedRef } from './rules/no-unresolved-refs';
 import { isPlainObject } from './utils';
@@ -35,6 +35,7 @@ export async function bundle(opts: {
   base?: string;
   skipRedoclyRegistryRefs?: boolean;
   removeUnusedComponents?: boolean;
+  keepUrlRefs?: boolean;
 }) {
   const {
     ref,
@@ -71,6 +72,7 @@ export async function bundleDocument(opts: {
   dereference?: boolean;
   skipRedoclyRegistryRefs?: boolean;
   removeUnusedComponents?: boolean;
+  keepUrlRefs?: boolean;
 }) {
   const {
     document,
@@ -80,6 +82,7 @@ export async function bundleDocument(opts: {
     dereference = false,
     skipRedoclyRegistryRefs = false,
     removeUnusedComponents = false,
+    keepUrlRefs = false,
   } = opts;
   const oasVersion = detectOpenAPI(document.parsed);
   const oasMajorVersion = openAPIMajor(oasVersion);
@@ -128,7 +131,14 @@ export async function bundleDocument(opts: {
       {
         severity: 'error',
         ruleId: 'bundler',
-        visitor: makeBundleVisitor(oasMajorVersion, dereference, skipRedoclyRegistryRefs, document, resolvedRefMap),
+        visitor: makeBundleVisitor(
+          oasMajorVersion,
+          dereference,
+          skipRedoclyRegistryRefs,
+          document,
+          resolvedRefMap,
+          keepUrlRefs,
+        ),
       },
       ...decorators,
     ] as any,
@@ -199,7 +209,8 @@ function makeBundleVisitor(
   dereference: boolean,
   skipRedoclyRegistryRefs: boolean,
   rootDocument: Document,
-  resolvedRefMap: ResolvedRefMap
+  resolvedRefMap: ResolvedRefMap,
+  keepUrlRefs: boolean,
 ) {
   let components: Record<string, Record<string, any>>;
 
@@ -224,6 +235,10 @@ function makeBundleVisitor(
           return;
         }
 
+        if (keepUrlRefs && isAbsoluteUrl(node.$ref)) {
+          return;
+        }
+
         const componentType = mapTypeToComponent(ctx.type.name, version);
         if (!componentType) {
           replaceRef(node, resolved, ctx);

package/src/config/__tests__/config-resolvers.test.ts

@@ -165,7 +165,7 @@ describe('resolveLint', () => {
     const lintConfig = {
       // This points to ./fixtures/resolve-remote-configs/remote-config.yaml
       extends: [
-        'https://raw.githubusercontent.com/Redocly/openapi-cli/master/packages/core/src/config/__tests__/fixtures/resolve-remote-configs/remote-config.yaml',
+        'https://raw.githubusercontent.com/Redocly/redocly-cli/master/packages/core/src/config/__tests__/fixtures/resolve-remote-configs/remote-config.yaml',
       ],
     };
 

package/src/config/all.ts

@@ -42,6 +42,7 @@ export default {
     spec: 'error',
     'no-invalid-schema-examples': 'error',
     'no-invalid-parameter-examples': 'error',
+    'scalar-property-missing-example': 'error',
   },
   oas3_0Rules: {
     'no-invalid-media-type-examples': 'error',

package/src/ref-utils.ts

@@ -72,6 +72,7 @@ export function isMappingRef(mapping: string) {
   return (
     mapping.startsWith('#') ||
     mapping.startsWith('https://') ||
+    mapping.startsWith('http://') ||
     mapping.startsWith('./') ||
     mapping.startsWith('../') ||
     mapping.indexOf('/') > -1

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

@@ -0,0 +1,207 @@
+import { outdent } from 'outdent';
+import { lintDocument } from '../../../lint';
+import { parseYamlToDocument, replaceSourceWithRef, makeConfig } from '../../../../__tests__/utils';
+import { BaseResolver } from '../../../resolve';
+
+describe('Oas3 scalar-property-missing-example', () => {
+  it('should report on a scalar property missing example', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.0.0
+        components:
+          schemas:
+            User:
+              type: object
+              properties:
+                email:
+                  description: User email address
+                  type: string
+                  format: email
+      `,
+      'foobar.yaml',
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'scalar-property-missing-example': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/components/schemas/User/properties/email",
+              "reportOnKey": true,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Scalar property should have \\"example\\" defined.",
+          "ruleId": "scalar-property-missing-example",
+          "severity": "error",
+          "suggest": Array [],
+        },
+      ]
+    `);
+  });
+});
+
+describe('Oas3.1 scalar-property-missing-example', () => {
+  it('should report on a scalar property missing example', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.1.0
+        components:
+          schemas:
+            User:
+              type: object
+              properties:
+                email:
+                  description: User email address
+                  type: string
+                  format: email
+      `,
+      'foobar.yaml',
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'scalar-property-missing-example': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/components/schemas/User/properties/email",
+              "reportOnKey": true,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Scalar property should have \\"example\\" or \\"examples\\" defined.",
+          "ruleId": "scalar-property-missing-example",
+          "severity": "error",
+          "suggest": Array [],
+        },
+      ]
+    `);
+  });
+
+  it('should not report on a scalar property with an example', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.1.0
+        components:
+          schemas:
+            User:
+              type: object
+              properties:
+                email:
+                  description: User email address
+                  type: string
+                  format: email
+                  example: john.smith@example.com
+      `,
+      'foobar.yaml',
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'scalar-property-missing-example': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`Array []`);
+  });
+
+  it('should not report on a scalar property with an examples', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.1.0
+        components:
+          schemas:
+            User:
+              type: object
+              properties:
+                email:
+                  description: User email address
+                  type: string
+                  format: email
+                  examples: 
+                  - john.smith@example.com
+                  - other@example.com
+      `,
+      'foobar.yaml',
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'scalar-property-missing-example': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`Array []`);
+  });
+
+  it('should not report on a non-scalar property missing an example', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.1.0
+        components:
+          schemas:
+            Pet:
+              type: object
+              required:
+                - photoUrls
+              properties:
+                photoUrls:
+                  description: The list of URL to a cute photos featuring pet
+                  type: array
+                  maxItems: 20
+                  xml:
+                    name: photoUrl
+                    wrapped: true
+                  items:
+                    type: string
+                    format: url
+      `,
+      'foobar.yaml',
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'scalar-property-missing-example': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`Array []`);
+  });
+
+  it('should not report on a scalar property of binary format missing an example', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.1.0
+        components:
+          schemas:
+            User:
+              type: object
+              properties:
+                responses:
+                  type: string
+                  format: binary
+      `,
+      'foobar.yaml',
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'scalar-property-missing-example': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`Array []`);
+  });
+});

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

@@ -0,0 +1,30 @@
+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?.[expectedHeader]) {
+              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,55 @@
+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 && !(propSchema as Oas3_1Schema).examples) {
+          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);
+}