@redocly/openapi-core 1.0.0 → 1.0.1

package/src/decorators/__tests__/remove-x-internal.test.ts

@@ -0,0 +1,316 @@
+import { outdent } from 'outdent';
+import { bundleDocument } from '../../bundle';
+import { BaseResolver } from '../../resolve';
+import { parseYamlToDocument, yamlSerializer, makeConfig } from '../../../__tests__/utils';
+
+describe('oas3 remove-x-internal', () => {
+  expect.addSnapshotSerializer(yamlSerializer);
+  const testDocument = parseYamlToDocument(
+    outdent`
+      openapi: 3.0.0
+      paths:
+        /pet:
+          removeit: true
+          get:
+            parameters:
+              - $ref: '#/components/parameters/x'
+      components:
+        parameters:
+          x:
+            name: x
+    `
+  );
+
+  it('should use `internalFlagProperty` option to remove internal paths', async () => {
+    const { bundle: res } = await bundleDocument({
+      document: testDocument,
+      externalRefResolver: new BaseResolver(),
+      config: await makeConfig({}, { 'remove-x-internal': { internalFlagProperty: 'removeit' } }),
+    });
+    expect(res.parsed).toMatchInlineSnapshot(`
+          openapi: 3.0.0
+          components:
+            parameters:
+              x:
+                name: x
+
+        `);
+  });
+
+  it('should clean types: Server, Operation, Parameter, PathItem, Example', async () => {
+    const testDoc = parseYamlToDocument(
+      outdent`
+        openapi: 3.1.0
+        servers:
+          - url: //petstore.swagger.io/v2
+            description: Default server
+            x-internal: true
+        paths:
+          /pet:
+            get:
+              x-internal: true
+              operationId: getPet
+              parameters:
+                - $ref: '#/components/parameters/x'
+            put:
+              parameters:
+                - name: Accept-Language
+                  x-internal: true
+                  in: header
+                  example: en-US
+                  required: false
+                - name: cookieParam
+                  x-internal: true
+                  in: cookie
+                  description: Some cookie
+                  required: true
+          /admin:
+            x-internal: true
+            post:
+              parameters:
+                - $ref: '#/components/parameters/y'
+          /store/order:
+            post:
+              operationId: placeOrder
+              responses:
+                '200':
+                  description: successful operation
+                  content:
+                    application/json:
+                      examples:
+                        response:
+                          x-internal: true
+                          value: OK
+        components:
+          parameters:
+            x:
+              name: x
+            y:
+              name: y
+      `
+    );
+    const { bundle: res } = await bundleDocument({
+      document: testDoc,
+      externalRefResolver: new BaseResolver(),
+      config: await makeConfig({}, { 'remove-x-internal': 'on' }),
+    });
+    expect(res.parsed).toMatchInlineSnapshot(`
+      openapi: 3.1.0
+      paths:
+        /pet:
+          put: {}
+        /store/order:
+          post:
+            operationId: placeOrder
+            responses:
+              '200':
+                description: successful operation
+                content:
+                  application/json: {}
+      components:
+        parameters:
+          x:
+            name: x
+          'y':
+            name: 'y'
+
+      `);
+  });
+
+  it('should clean types: Schema, Response, RequestBody, MediaType, Callback', async () => {
+    const testDoc = parseYamlToDocument(
+      outdent`
+        openapi: 3.1.0
+        paths:
+          /pet:
+            post:
+              summary: test
+              requestBody:
+                x-internal: true
+                content:
+                  application/x-www-form-urlencoded:
+                    schema:
+                      type: object
+          /store/order:
+            post:
+              operationId: storeOrder
+              parameters:
+                - name: api_key
+                  schema:
+                    x-internal: true
+                    type: string
+              responses:
+                '200':
+                  x-internal: true
+                  content:
+                    application/json:
+                      examples:
+                        response:
+                          value: OK
+              requestBody:
+                content:
+                  application/x-www-form-urlencoded:
+                    x-internal: true
+                    schema:
+                      type: object
+              callbacks:
+                orderInProgress:
+                  x-internal: true
+                  '{$request.body#/callbackUrl}?event={$request.body#/eventName}':
+                    servers:
+                      - url: //callback-url.path-level/v1
+                        description: Path level server
+      `
+    );
+    const { bundle: res } = await bundleDocument({
+      document: testDoc,
+      externalRefResolver: new BaseResolver(),
+      config: await makeConfig({}, { 'remove-x-internal': 'on' }),
+    });
+
+    expect(res.parsed).toMatchInlineSnapshot(`
+      openapi: 3.1.0
+      paths:
+        /pet:
+          post:
+            summary: test
+        /store/order:
+          post:
+            operationId: storeOrder
+            parameters:
+              - name: api_key
+            requestBody: {}
+      components: {}
+
+      `);
+  });
+
+  it('should remove refs', async () => {
+    const testDoc = parseYamlToDocument(
+      outdent`
+        openapi: 3.0.1
+        info:
+          version: 1.0.0
+          title: Test API
+        paths:
+          /test1:
+            get:
+              parameters:
+                - $ref: '#/components/parameters/Internal'
+                - in: query
+                  name: inline
+                  schema:
+                    type: string
+                - in: query
+                  name: inline-internal
+                  schema:
+                    type: string
+                  x-internal: true
+          /test2:
+            get:
+              parameters:
+                - $ref: '#/components/parameters/Public'
+                - $ref: '#/components/parameters/Internal'
+              requestBody:
+                $ref: '#/components/requestBodies/Public'
+        components:
+          requestBodies:
+            Public:
+              content:
+                application/json:
+                  schema:
+                    type: string
+              required: true
+              x-internal: true
+          parameters:
+            Public:
+              in: path
+              name: product_id
+              schema:
+                type: string
+            Internal:
+              in: header
+              name: X-Vendor
+              schema:
+                type: string
+              x-internal: true
+      `
+    );
+    const { bundle: res } = await bundleDocument({
+      document: testDoc,
+      externalRefResolver: new BaseResolver(),
+      config: await makeConfig({}, { 'remove-x-internal': 'on' }),
+    });
+    expect(res.parsed).toMatchInlineSnapshot(`
+      openapi: 3.0.1
+      info:
+        version: 1.0.0
+        title: Test API
+      paths:
+        /test1:
+          get:
+            parameters:
+              - in: query
+                name: inline
+                schema:
+                  type: string
+        /test2:
+          get:
+            parameters:
+              - $ref: '#/components/parameters/Public'
+      components:
+        parameters:
+          Public:
+            in: path
+            name: product_id
+            schema:
+              type: string
+
+    `);
+  });
+});
+
+describe('oas2 remove-x-internal', () => {
+  it('should clean types - base test', async () => {
+    const testDoc = parseYamlToDocument(
+      outdent`
+        swagger: '2.0'
+        host: api.instagram.com
+        paths:
+          '/geographies/{geo-id}/media/recent':
+            get:
+              parameters:
+                - description: The geography ID.
+                  x-internal: true
+                  in: path
+                  name: geo-id
+                  required: true
+                  type: string
+                - description: Max number of media to return.
+                  x-internal: true
+                  format: int32
+                  in: query
+                  name: count
+                  required: false
+                  type: integer
+              responses:
+                '200':
+                  x-internal: true
+                  description: List of recent media entries.
+      `
+    );
+    const { bundle: res } = await bundleDocument({
+      document: testDoc,
+      externalRefResolver: new BaseResolver(),
+      config: await makeConfig({}, { 'remove-x-internal': 'on' }),
+    });
+    expect(res.parsed).toMatchInlineSnapshot(`
+          swagger: '2.0'
+          host: api.instagram.com
+          paths:
+            /geographies/{geo-id}/media/recent:
+              get: {}
+
+        `);
+  });
+});

package/src/decorators/__tests__/resources/request.yaml

@@ -0,0 +1,3 @@
+def:
+  value:
+    b: from external file

package/src/decorators/__tests__/resources/response.yaml

@@ -0,0 +1,3 @@
+def:
+  value:
+    name: test response name

package/src/decorators/common/filters/filter-helper.ts

@@ -0,0 +1,72 @@
+import { UserContext } from '../../../walk';
+import { isRef } from '../../../ref-utils';
+import { isEmptyArray, isEmptyObject, isPlainObject } from '../../../utils';
+
+export function filter(node: any, ctx: UserContext, criteria: (item: any) => boolean) {
+  const { parent, key } = ctx;
+  let didDelete = false;
+  if (Array.isArray(node)) {
+    for (let i = 0; i < node.length; i++) {
+      if (isRef(node[i])) {
+        const resolved = ctx.resolve(node[i]);
+        if (criteria(resolved.node)) {
+          node.splice(i, 1);
+          didDelete = true;
+          i--;
+        }
+      }
+      if (criteria(node[i])) {
+        node.splice(i, 1);
+        didDelete = true;
+        i--;
+      }
+    }
+  } else if (isPlainObject(node)) {
+    for (const key of Object.keys(node)) {
+      node = node as any;
+      if (isRef(node[key])) {
+        const resolved = ctx.resolve(node[key]);
+        if (criteria(resolved.node)) {
+          delete node[key];
+          didDelete = true;
+        }
+      }
+      if (criteria(node[key])) {
+        delete node[key];
+        didDelete = true;
+      }
+    }
+  }
+  if (didDelete && (isEmptyObject(node) || isEmptyArray(node))) {
+    delete parent[key];
+  }
+}
+
+export function checkIfMatchByStrategy(
+  nodeValue: any,
+  decoratorValue: any,
+  strategy: 'all' | 'any'
+): boolean {
+  if (nodeValue === undefined || decoratorValue === undefined) {
+    return false;
+  }
+
+  if (!Array.isArray(decoratorValue) && !Array.isArray(nodeValue)) {
+    return nodeValue === decoratorValue;
+  }
+
+  decoratorValue = toArrayIfNeeded<string>(decoratorValue);
+  nodeValue = toArrayIfNeeded<string>(nodeValue);
+
+  if (strategy === 'any') {
+    return decoratorValue.some((item: string) => nodeValue.includes(item));
+  }
+  if (strategy === 'all') {
+    return decoratorValue.every((item: string) => nodeValue.includes(item));
+  }
+  return false;
+}
+
+function toArrayIfNeeded<T>(value: T | T[]): T[] {
+  return Array.isArray(value) ? value : [value];
+}

package/src/decorators/common/filters/filter-in.ts

@@ -0,0 +1,18 @@
+import { Oas2Decorator, Oas3Decorator } from '../../../visitors';
+import { checkIfMatchByStrategy, filter } from './filter-helper';
+
+const DEFAULT_STRATEGY = 'any';
+
+export const FilterIn: Oas3Decorator | Oas2Decorator = ({ property, value, matchStrategy }) => {
+  const strategy = matchStrategy || DEFAULT_STRATEGY;
+  const filterInCriteria = (item: any) =>
+    item?.[property] && !checkIfMatchByStrategy(item?.[property], value, strategy);
+
+  return {
+    any: {
+      enter: (node, ctx) => {
+        filter(node, ctx, filterInCriteria);
+      },
+    },
+  };
+};

package/src/decorators/common/filters/filter-out.ts

@@ -0,0 +1,18 @@
+import { Oas2Decorator, Oas3Decorator } from '../../../visitors';
+import { checkIfMatchByStrategy, filter } from './filter-helper';
+
+const DEFAULT_STRATEGY = 'any';
+
+export const FilterOut: Oas3Decorator | Oas2Decorator = ({ property, value, matchStrategy }) => {
+  const strategy = matchStrategy || DEFAULT_STRATEGY;
+  const filterOutCriteria = (item: any) =>
+    checkIfMatchByStrategy(item?.[property], value, strategy);
+
+  return {
+    any: {
+      enter: (node, ctx) => {
+        filter(node, ctx, filterOutCriteria);
+      },
+    },
+  };
+};

package/src/decorators/common/info-description-override.ts

@@ -0,0 +1,24 @@
+import { Oas3Decorator, Oas2Decorator } from '../../visitors';
+import { readFileAsStringSync } from '../../utils';
+import { UserContext } from '../../walk';
+
+export const InfoDescriptionOverride: Oas3Decorator | Oas2Decorator = ({ filePath }) => {
+  return {
+    Info: {
+      leave(info, { report, location }: UserContext) {
+        if (!filePath)
+          throw new Error(
+            `Parameter "filePath" is not provided for "info-description-override" rule`
+          );
+        try {
+          info.description = readFileAsStringSync(filePath);
+        } catch (e) {
+          report({
+            message: `Failed to read markdown override file for "info.description".\n${e.message}`,
+            location: location.child('description'),
+          });
+        }
+      },
+    },
+  };
+};

package/src/decorators/common/info-override.ts

@@ -0,0 +1,15 @@
+import { Oas3Decorator, Oas2Decorator } from '../../visitors';
+
+export const InfoOverride: Oas3Decorator | Oas2Decorator = (newInfo) => {
+  return {
+    Info: {
+      leave(info) {
+        if (typeof newInfo !== 'object' || Array.isArray(newInfo) || newInfo === null) {
+          throw new Error(`"info-override" decorator should be called with an object`);
+        }
+        const { severity: _, ...rest } = newInfo;
+        Object.assign(info, rest);
+      },
+    },
+  };
+};

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/common/operation-description-override.ts

@@ -0,0 +1,30 @@
+import { Oas3Decorator, Oas2Decorator } from '../../visitors';
+import { Oas2Operation } from '../../typings/swagger';
+import { Oas3Operation } from '../../typings/openapi';
+import { readFileAsStringSync } from '../../utils';
+import { UserContext } from '../../walk';
+
+export const OperationDescriptionOverride: Oas3Decorator | Oas2Decorator = ({ operationIds }) => {
+  return {
+    Operation: {
+      leave(operation: Oas2Operation | Oas3Operation, { report, location }: UserContext) {
+        if (!operation.operationId) return;
+        if (!operationIds)
+          throw new Error(
+            `Parameter "operationIds" is not provided for "operation-description-override" rule`
+          );
+        const operationId = operation.operationId;
+        if (operationIds[operationId]) {
+          try {
+            operation.description = readFileAsStringSync(operationIds[operationId]);
+          } catch (e) {
+            report({
+              message: `Failed to read markdown override file for operation "${operationId}".\n${e.message}`,
+              location: location.child('operationId').key(),
+            });
+          }
+        }
+      },
+    },
+  };
+};

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

@@ -0,0 +1,25 @@
+import { UserContext } from '../../walk';
+import { isRedoclyRegistryURL } from '../../redocly';
+
+import { Oas3Decorator, Oas2Decorator } from '../../visitors';
+
+export const RegistryDependencies: Oas3Decorator | Oas2Decorator = () => {
+  const registryDependencies = new Set<string>();
+
+  return {
+    Root: {
+      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 (isRedoclyRegistryURL(link)) {
+          registryDependencies.add(link);
+        }
+      }
+    },
+  };
+};

package/src/decorators/common/remove-x-internal.ts

@@ -0,0 +1,59 @@
+import { Oas3Decorator, Oas2Decorator } from '../../visitors';
+import { isEmptyArray, isEmptyObject, isPlainObject } from '../../utils';
+import { UserContext } from '../../walk';
+import { isRef } from '../../ref-utils';
+
+const DEFAULT_INTERNAL_PROPERTY_NAME = 'x-internal';
+
+export const RemoveXInternal: Oas3Decorator | Oas2Decorator = ({ internalFlagProperty }) => {
+  const hiddenTag = internalFlagProperty || DEFAULT_INTERNAL_PROPERTY_NAME;
+
+  function removeInternal(node: any, ctx: UserContext) {
+    const { parent, key } = ctx;
+    let didDelete = false;
+    if (Array.isArray(node)) {
+      for (let i = 0; i < node.length; i++) {
+        if (isRef(node[i])) {
+          const resolved = ctx.resolve(node[i]);
+          if (resolved.node?.[hiddenTag]) {
+            node.splice(i, 1);
+            didDelete = true;
+            i--;
+          }
+        }
+        if (node[i]?.[hiddenTag]) {
+          node.splice(i, 1);
+          didDelete = true;
+          i--;
+        }
+      }
+    } else if (isPlainObject(node)) {
+      for (const key of Object.keys(node)) {
+        node = node as any;
+        if (isRef(node[key])) {
+          const resolved = ctx.resolve(node[key]);
+          if (resolved.node?.[hiddenTag]) {
+            delete node[key];
+            didDelete = true;
+          }
+        }
+        if (node[key]?.[hiddenTag]) {
+          delete node[key];
+          didDelete = true;
+        }
+      }
+    }
+
+    if (didDelete && (isEmptyObject(node) || isEmptyArray(node))) {
+      delete parent[key];
+    }
+  }
+
+  return {
+    any: {
+      enter: (node, ctx) => {
+        removeInternal(node, ctx);
+      },
+    },
+  };
+};

package/src/decorators/common/tag-description-override.ts

@@ -0,0 +1,25 @@
+import { Oas3Decorator, Oas2Decorator } from '../../visitors';
+import { readFileAsStringSync } from '../../utils';
+import { UserContext } from '../../walk';
+
+export const TagDescriptionOverride: Oas3Decorator | Oas2Decorator = ({ tagNames }) => {
+  return {
+    Tag: {
+      leave(tag, { report }: UserContext) {
+        if (!tagNames)
+          throw new Error(
+            `Parameter "tagNames" is not provided for "tag-description-override" rule`
+          );
+        if (tagNames[tag.name]) {
+          try {
+            tag.description = readFileAsStringSync(tagNames[tag.name]);
+          } catch (e) {
+            report({
+              message: `Failed to read markdown override file for tag "${tag.name}".\n${e.message}`,
+            });
+          }
+        }
+      },
+    },
+  };
+};