@redocly/openapi-core 1.0.0-beta.100

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/spec.ts

@@ -0,0 +1,143 @@
+import type { Oas3Rule, Oas2Rule } from '../../visitors';
+import { isNamedType } from '../../types';
+import { oasTypeOf, matchesJsonSchemaType, getSuggest } from '../utils';
+import { isRef } from '../../ref-utils';
+import { isPlainObject } from '../../utils';
+
+export const OasSpec: Oas3Rule | Oas2Rule = () => {
+  return {
+    any(node: any, { report, type, location, key, resolve, ignoreNextVisitorsOnNode } ) {
+      const nodeType = oasTypeOf(node);
+
+      if (type.items) {
+        if (nodeType !== 'array') {
+          report({
+            message: `Expected type \`${type.name}\` (array) but got \`${nodeType}\``,
+          });
+          ignoreNextVisitorsOnNode();
+        }
+        return;
+      } else if (nodeType !== 'object') {
+        report({
+          message: `Expected type \`${type.name}\` (object) but got \`${nodeType}\``,
+        });
+        ignoreNextVisitorsOnNode();
+        return;
+      }
+
+      const required =
+        typeof type.required === 'function' ? type.required(node, key) : type.required;
+
+      for (let propName of required || []) {
+        if (!(node as object).hasOwnProperty(propName)) {
+          report({
+            message: `The field \`${propName}\` must be present on this level.`,
+            location: [{ reportOnKey: true }],
+          });
+        }
+      }
+
+      const allowed = type.allowed?.(node);
+      if (allowed && isPlainObject(node)) {
+        for (const propName in node) {
+          if (allowed.includes(propName) ||
+           (type.extensionsPrefix && propName.startsWith(type.extensionsPrefix)) ||
+           !Object.keys(type.properties).includes(propName)
+          ) {
+            continue;
+          }
+          report({
+            message: `The field \`${propName}\` is not allowed here.`,
+            location: location.child([propName]).key()
+          });
+        }
+      }
+
+      const requiredOneOf = type.requiredOneOf || null;
+      if (requiredOneOf) {
+        let hasProperty = false;
+        for (let propName of requiredOneOf || []) {
+          if ((node as object).hasOwnProperty(propName)) {
+            hasProperty = true;
+          }
+        }
+        if (!hasProperty)
+          report({
+            message: `Must contain at least one of the following fields: ${type.requiredOneOf?.join(', ')}.`,
+            location: [{ reportOnKey: true }],
+          });
+      }
+
+      for (const propName of Object.keys(node)) {
+        const propLocation = location.child([propName]);
+        let propValue = node[propName];
+
+        let propType = type.properties[propName];
+        if (propType === undefined) propType = type.additionalProperties;
+        if (typeof propType === 'function') propType = propType(propValue, propName);
+
+        if (isNamedType(propType)) {
+          continue; // do nothing for named schema, it is executed with the next any call
+        }
+
+        const propSchema = propType;
+        const propValueType = oasTypeOf(propValue);
+
+        if (propSchema === undefined) {
+          if (propName.startsWith('x-')) continue;
+          report({
+            message: `Property \`${propName}\` is not expected here.`,
+            suggest: getSuggest(propName, Object.keys(type.properties)),
+            location: propLocation.key(),
+          });
+          continue;
+        }
+
+        if (propSchema === null) {
+          continue; // just defined, no validation
+        }
+
+        if (propSchema.resolvable !== false && isRef(propValue)) {
+          propValue = resolve(propValue).node;
+        }
+
+        if (propSchema.enum) {
+          if (!propSchema.enum.includes(propValue)) {
+            report({
+              location: propLocation,
+              message: `\`${propName}\` can be one of the following only: ${propSchema.enum
+                .map((i) => `"${i}"`)
+                .join(', ')}.`,
+              suggest: getSuggest(propValue, propSchema.enum),
+            });
+          }
+        } else if (propSchema.type && !matchesJsonSchemaType(propValue, propSchema.type, false)) {
+          report({
+            message: `Expected type \`${propSchema.type}\` but got \`${propValueType}\`.`,
+            location: propLocation,
+          });
+        } else if (propValueType === 'array' && propSchema.items?.type) {
+          const itemsType = propSchema.items?.type;
+          for (let i = 0; i < propValue.length; i++) {
+            const item = propValue[i];
+            if (!matchesJsonSchemaType(item, itemsType, false)) {
+              report({
+                message: `Expected type \`${itemsType}\` but got \`${oasTypeOf(item)}\`.`,
+                location: propLocation.child([i]),
+              });
+            }
+          }
+        }
+
+        if (typeof propSchema.minimum === 'number') {
+          if (propSchema.minimum > node[propName]) {
+            report({
+              message: `The value of the ${propName} field must be greater than or equal to ${propSchema.minimum}`,
+              location: location.child([propName]),
+            })
+          }
+        }
+      }
+    },
+  };
+};

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

@@ -0,0 +1,10 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { validateDefinedAndNonEmpty } from '../utils';
+
+export const TagDescription: Oas3Rule | Oas2Rule = () => {
+  return {
+    Tag(tag, ctx) {
+      validateDefinedAndNonEmpty('description', tag, ctx);
+    },
+  };
+};

package/src/rules/common/tags-alphabetical.ts

@@ -0,0 +1,20 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { Oas2Definition } from '../../typings/swagger';
+import { Oas3Definition } from '../../typings/openapi';
+import { UserContext } from '../../walk';
+
+export const TagsAlphabetical: Oas3Rule | Oas2Rule = () => {
+  return {
+    DefinitionRoot(root: Oas2Definition | Oas3Definition, { report, location }: UserContext) {
+      if (!root.tags) return;
+      for (let i = 0; i < root.tags.length - 1; i++) {
+        if (root.tags[i].name > root.tags[i + 1].name) {
+          report({
+            message: 'The `tags` array should be in alphabetical order.',
+            location: location.child(['tags', i]),
+          });
+        }
+      }
+    },
+  };
+};

package/src/rules/no-unresolved-refs.ts

@@ -0,0 +1,51 @@
+import { Oas3Rule } from '../visitors';
+import { YamlParseError } from '../resolve';
+import { ResolveResult, Problem } from '../walk';
+import { Location } from '../ref-utils';
+
+export const NoUnresolvedRefs: Oas3Rule = () => {
+  return {
+    ref: {
+      leave(_, { report, location }, resolved) {
+        if (resolved.node !== undefined) return;
+        reportUnresolvedRef(resolved, report, location);
+      },
+    },
+    DiscriminatorMapping(mapping, { report, resolve, location }) {
+      for (const mappingName of Object.keys(mapping)) {
+        const resolved = resolve({ $ref: mapping[mappingName] });
+        if (resolved.node !== undefined) return;
+
+        reportUnresolvedRef(resolved, report, location.child(mappingName));
+      }
+    },
+  };
+};
+
+export function reportUnresolvedRef(
+  resolved: ResolveResult<any>,
+  report: (m: Problem) => void,
+  location: Location,
+) {
+  const error = resolved.error;
+  if (error instanceof YamlParseError) {
+    report({
+      message: 'Failed to parse: ' + error.message,
+      location: {
+        source: error.source,
+        pointer: undefined,
+        start: {
+          col: error.col,
+          line: error.line,
+        },
+      },
+    });
+  }
+
+  const message = resolved.error?.message;
+
+  report({
+    location,
+    message: `Can't resolve $ref${message ? ': ' + message : ''}`,
+  });
+}

package/src/rules/oas2/__tests__/boolean-parameter-prefixes.test.ts

@@ -0,0 +1,110 @@
+import { outdent } from 'outdent';
+import { parseYamlToDocument, replaceSourceWithRef, makeConfig } from '../../../../__tests__/utils';
+import { lintDocument } from '../../../lint';
+import { BaseResolver } from '../../../resolve';
+
+describe('oas2 boolean-parameter-prefixes', () => {
+  it('should report on boolean param without prefix', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        swagger: '2.0'
+        paths:
+          '/test':
+            parameters:
+            - name: a
+              in: path
+              type: boolean
+      `,
+      'foobar.yaml',
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'boolean-parameter-prefixes': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/paths/~1test/parameters/0/name",
+              "reportOnKey": false,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Boolean parameter \`a\` should have \`is\` or \`has\` prefix.",
+          "ruleId": "boolean-parameter-prefixes",
+          "severity": "error",
+          "suggest": Array [],
+        },
+      ]
+    `);
+  });
+
+  it('should not report on boolean param with prefix', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.0.0
+          paths:
+            '/test':
+              parameters:
+                - name: hasA
+                  in: path
+                  schema:
+                    type: boolean
+                - name: isA
+                  in: path
+                  schema:
+                    type: boolean
+                - name: has_a
+                  in: path
+                  schema:
+                    type: boolean
+                - name: is-a
+                  in: path
+                  schema:
+                    type: boolean
+      `,
+      'foobar.yaml',
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'boolean-parameter-prefixes': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`Array []`);
+  });
+
+  it('should not report on boolean param with custom prefix', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.0.0
+          paths:
+            '/test':
+              parameters:
+              - name: should-a
+                in: query
+                schema:
+                  type: boolean
+      `,
+      'foobar.yaml',
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'boolean-parameter-prefixes': {
+          severity: 'error',
+          prefixes: ['should'],
+        },
+      }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`Array []`);
+  });
+});

package/src/rules/oas2/__tests__/response-contains-header.test.ts

@@ -0,0 +1,174 @@
+import { outdent } from 'outdent';
+import { lintDocument } from '../../../lint';
+import { parseYamlToDocument, makeConfig } from '../../../../__tests__/utils';
+import { BaseResolver } from '../../../resolve';
+
+describe('Oas2 response-contains-header', () => {
+  it('should report a response object not containing the header', async () => {
+    const document = parseYamlToDocument(outdent`
+      swagger: '2.0'
+      schemes:
+        - https
+      basePath: /v2
+      paths:
+        '/accounts/{accountId}':
+          get:
+            description: Retrieve a sub account under the master account.
+            operationId: account
+            responses:
+              '201':
+                description: Account Created
+                headers:
+                  Content-Location:
+                    description: Location of created Account
+                    type: string
+              '404':
+                description: User not found
+    `);
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'response-contains-header': {
+          severity: 'error',
+          names: { '2xx': ['Content-Length'], '4xx': ['Content-Length'] },
+        },
+      }),
+    });
+    expect(results).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/paths/~1accounts~1{accountId}/get/responses/201/headers",
+              "reportOnKey": true,
+              "source": Source {
+                "absoluteRef": "",
+                "body": "swagger: '2.0'
+      schemes:
+        - https
+      basePath: /v2
+      paths:
+        '/accounts/{accountId}':
+          get:
+            description: Retrieve a sub account under the master account.
+            operationId: account
+            responses:
+              '201':
+                description: Account Created
+                headers:
+                  Content-Location:
+                    description: Location of created Account
+                    type: string
+              '404':
+                description: User not found",
+                "mimeType": undefined,
+              },
+            },
+          ],
+          "message": "Response object must contain a \\"Content-Length\\" header.",
+          "ruleId": "response-contains-header",
+          "severity": "error",
+          "suggest": Array [],
+        },
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/paths/~1accounts~1{accountId}/get/responses/404/headers",
+              "reportOnKey": true,
+              "source": Source {
+                "absoluteRef": "",
+                "body": "swagger: '2.0'
+      schemes:
+        - https
+      basePath: /v2
+      paths:
+        '/accounts/{accountId}':
+          get:
+            description: Retrieve a sub account under the master account.
+            operationId: account
+            responses:
+              '201':
+                description: Account Created
+                headers:
+                  Content-Location:
+                    description: Location of created Account
+                    type: string
+              '404':
+                description: User not found",
+                "mimeType": undefined,
+              },
+            },
+          ],
+          "message": "Response object must contain a \\"Content-Length\\" header.",
+          "ruleId": "response-contains-header",
+          "severity": "error",
+          "suggest": Array [],
+        },
+      ]
+    `);
+  });
+
+  it('should not report a response object containing the header nor not applicable', async () => {
+    const document = parseYamlToDocument(outdent`
+      swagger: '2.0'
+      schemes:
+        - https
+      basePath: /v2
+      paths:
+        '/accounts/{accountId}':
+          get:
+            description: Retrieve a sub account under the master account.
+            operationId: account
+            responses:
+              '201':
+                description: Account Created
+                headers:
+                  Content-Length:
+                    description: calls per hour allowed by the user
+                    schema:
+                      type: integer
+                      format: int32
+              '404':
+                description: User not found
+		`);
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'response-contains-header': {
+          severity: 'error',
+          names: { '2xx': ['Content-Length'], '400': ['Content-Length'] },
+        },
+      }),
+    });
+    expect(results).toMatchInlineSnapshot(`Array []`);
+  });
+
+  it('should not report a response object when there is no `names` section defined', async () => {
+    const document = parseYamlToDocument(outdent`
+      swagger: '2.0'
+      schemes:
+        - https
+      basePath: /v2
+      paths:
+        '/accounts/{accountId}':
+          get:
+            description: Retrieve a sub account under the master account.
+            operationId: account
+            responses:
+              '404':
+                description: User not found
+		`);
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'response-contains-header': {
+          severity: 'error',
+        },
+      }),
+    });
+    expect(results).toMatchInlineSnapshot(`Array []`);
+  });
+});