mcp-openapi-schema-explorer 1.0.0

package/test/__tests__/unit/rendering/paths.test.ts

@@ -0,0 +1,115 @@
+import { OpenAPIV3 } from 'openapi-types';
+import { RenderablePaths } from '../../../../src/rendering/paths';
+import { RenderContext } from '../../../../src/rendering/types';
+import { IFormatter, JsonFormatter } from '../../../../src/services/formatters';
+
+// Mock Formatter & Context
+const mockFormatter: IFormatter = new JsonFormatter();
+const mockContext: RenderContext = {
+  formatter: mockFormatter,
+  baseUri: 'openapi://',
+};
+
+// Sample Paths Object Fixture
+const samplePaths: OpenAPIV3.PathsObject = {
+  '/users': {
+    get: {
+      summary: 'List Users',
+      responses: { '200': { description: 'OK' } },
+    },
+    post: {
+      summary: 'Create User',
+      responses: { '201': { description: 'Created' } },
+    },
+  },
+  '/users/{userId}': {
+    get: {
+      summary: 'Get User by ID',
+      responses: { '200': { description: 'OK' } },
+    },
+    delete: {
+      // No summary
+      responses: { '204': { description: 'No Content' } },
+    },
+  },
+  // Removed /ping path with custom operation to avoid type errors
+};
+
+const emptyPaths: OpenAPIV3.PathsObject = {};
+
+describe('RenderablePaths', () => {
+  describe('renderList', () => {
+    it('should render a list of paths and methods correctly', () => {
+      const renderablePaths = new RenderablePaths(samplePaths);
+      const result = renderablePaths.renderList(mockContext);
+
+      expect(result).toHaveLength(1);
+      expect(result[0].uriSuffix).toBe('paths');
+      expect(result[0].renderAsList).toBe(true);
+      expect(result[0].isError).toBeUndefined();
+
+      // Define expected output lines based on the new format
+      const expectedLineUsers = 'GET POST /users'; // Methods sorted alphabetically and uppercased
+      const expectedLineUserDetail = 'DELETE GET /users/{userId}'; // Methods sorted alphabetically and uppercased
+
+      // Check essential parts instead of exact match
+      expect(result[0].data).toContain('Hint:');
+      expect(result[0].data).toContain('openapi://paths/{encoded_path}');
+      expect(result[0].data).toContain('openapi://paths/{encoded_path}/{method}');
+      expect(result[0].data).toContain(expectedLineUsers);
+      expect(result[0].data).toContain(expectedLineUserDetail);
+    });
+
+    it('should handle empty paths object', () => {
+      const renderablePaths = new RenderablePaths(emptyPaths);
+      const result = renderablePaths.renderList(mockContext);
+
+      expect(result).toHaveLength(1);
+      expect(result[0]).toEqual({
+        uriSuffix: 'paths',
+        data: 'No paths found in the specification.',
+        renderAsList: true,
+      });
+    });
+
+    it('should handle undefined paths object', () => {
+      const renderablePaths = new RenderablePaths(undefined);
+      const result = renderablePaths.renderList(mockContext);
+
+      expect(result).toHaveLength(1);
+      expect(result[0]).toEqual({
+        uriSuffix: 'paths',
+        data: 'No paths found in the specification.',
+        renderAsList: true,
+      });
+    });
+  });
+
+  describe('renderDetail', () => {
+    it('should delegate to renderList', () => {
+      const renderablePaths = new RenderablePaths(samplePaths);
+      const listResult = renderablePaths.renderList(mockContext);
+      const detailResult = renderablePaths.renderDetail(mockContext);
+      // Check if the output is the same as renderList
+      expect(detailResult).toEqual(listResult);
+    });
+  });
+
+  describe('getPathItem', () => {
+    it('should return the correct PathItemObject', () => {
+      const renderablePaths = new RenderablePaths(samplePaths);
+      expect(renderablePaths.getPathItem('/users')).toBe(samplePaths['/users']);
+      expect(renderablePaths.getPathItem('/users/{userId}')).toBe(samplePaths['/users/{userId}']);
+    });
+
+    it('should return undefined for non-existent path', () => {
+      const renderablePaths = new RenderablePaths(samplePaths);
+      expect(renderablePaths.getPathItem('/nonexistent')).toBeUndefined();
+    });
+
+    it('should return undefined if paths object is undefined', () => {
+      const renderablePaths = new RenderablePaths(undefined);
+      expect(renderablePaths.getPathItem('/users')).toBeUndefined();
+    });
+  });
+});

package/test/__tests__/unit/services/formatters.test.ts

@@ -0,0 +1,109 @@
+import { dump as yamlDump } from 'js-yaml';
+import {
+  JsonFormatter,
+  YamlFormatter,
+  MinifiedJsonFormatter,
+  createFormatter,
+} from '../../../../src/services/formatters.js';
+
+describe('Formatters', () => {
+  const testData = {
+    method: 'GET',
+    path: '/test',
+    summary: 'Test endpoint',
+    parameters: [
+      {
+        name: 'id',
+        in: 'path',
+        required: true,
+        schema: { type: 'string' },
+      },
+    ],
+  };
+
+  describe('JsonFormatter', () => {
+    const formatter = new JsonFormatter();
+
+    it('should format data as JSON with proper indentation', () => {
+      const result = formatter.format(testData);
+      expect(result).toBe(JSON.stringify(testData, null, 2));
+    });
+
+    it('should return application/json mime type', () => {
+      expect(formatter.getMimeType()).toBe('application/json');
+    });
+
+    it('should handle empty objects', () => {
+      expect(formatter.format({})).toBe('{}');
+    });
+
+    it('should handle null values', () => {
+      expect(formatter.format(null)).toBe('null');
+    });
+  });
+
+  describe('YamlFormatter', () => {
+    const formatter = new YamlFormatter();
+
+    it('should format data as YAML', () => {
+      const result = formatter.format(testData);
+      expect(result).toBe(
+        yamlDump(testData, {
+          indent: 2,
+          lineWidth: -1,
+          noRefs: true,
+        })
+      );
+    });
+
+    it('should return text/yaml mime type', () => {
+      expect(formatter.getMimeType()).toBe('text/yaml');
+    });
+
+    it('should handle empty objects', () => {
+      expect(formatter.format({})).toBe('{}\n');
+    });
+
+    it('should handle null values', () => {
+      expect(formatter.format(null)).toBe('null\n');
+    });
+  });
+
+  describe('MinifiedJsonFormatter', () => {
+    const formatter = new MinifiedJsonFormatter();
+
+    it('should format data as minified JSON', () => {
+      const result = formatter.format(testData);
+      expect(result).toBe(JSON.stringify(testData));
+    });
+
+    it('should return application/json mime type', () => {
+      expect(formatter.getMimeType()).toBe('application/json');
+    });
+
+    it('should handle empty objects', () => {
+      expect(formatter.format({})).toBe('{}');
+    });
+
+    it('should handle null values', () => {
+      expect(formatter.format(null)).toBe('null');
+    });
+  });
+
+  describe('createFormatter', () => {
+    it('should create JsonFormatter for json format', () => {
+      const formatter = createFormatter('json');
+      expect(formatter).toBeInstanceOf(JsonFormatter);
+    });
+
+    it('should create YamlFormatter for yaml format', () => {
+      const formatter = createFormatter('yaml');
+      expect(formatter).toBeInstanceOf(YamlFormatter);
+    });
+
+    it('should create MinifiedJsonFormatter for json-minified format', () => {
+      const formatter = createFormatter('json-minified');
+      expect(formatter).toBeInstanceOf(MinifiedJsonFormatter);
+    });
+  });
+});

package/test/__tests__/unit/services/reference-transform.test.ts

@@ -0,0 +1,320 @@
+import { OpenAPIV3 } from 'openapi-types';
+import {
+  OpenAPITransformer,
+  ReferenceTransformService,
+  TransformContext,
+} from '../../../../src/services/reference-transform';
+
+describe('ReferenceTransformService', () => {
+  let service: ReferenceTransformService;
+  let transformer: OpenAPITransformer;
+
+  beforeEach(() => {
+    service = new ReferenceTransformService();
+    transformer = new OpenAPITransformer();
+    service.registerTransformer('openapi', transformer);
+  });
+
+  it('throws error for unknown format', () => {
+    const context: TransformContext = {
+      resourceType: 'endpoint',
+      format: 'unknown' as 'openapi' | 'asyncapi' | 'graphql',
+    };
+
+    expect(() => service.transformDocument({}, context)).toThrow(
+      'No transformer registered for format: unknown'
+    );
+  });
+
+  it('transforms document using registered transformer', () => {
+    const context: TransformContext = {
+      resourceType: 'endpoint',
+      format: 'openapi',
+      path: '/tasks',
+      method: 'get',
+    };
+
+    const doc: OpenAPIV3.Document = {
+      openapi: '3.0.0',
+      info: {
+        title: 'Test API',
+        version: '1.0.0',
+      },
+      paths: {
+        '/tasks': {
+          get: {
+            responses: {
+              '200': {
+                description: 'Success',
+                content: {
+                  'application/json': {
+                    schema: {
+                      $ref: '#/components/schemas/Task',
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+
+    const result = service.transformDocument(doc, context);
+    const operation = result.paths?.['/tasks']?.get;
+    const response = operation?.responses?.['200'];
+    expect(response).toBeDefined();
+    expect('content' in response!).toBeTruthy();
+    const responseObj = response! as OpenAPIV3.ResponseObject;
+    expect(responseObj.content?.['application/json']?.schema).toBeDefined();
+    // Expect the new format
+    expect(responseObj.content!['application/json'].schema).toEqual({
+      $ref: 'openapi://components/schemas/Task',
+    });
+  });
+});
+
+describe('OpenAPITransformer', () => {
+  let transformer: OpenAPITransformer;
+
+  beforeEach(() => {
+    transformer = new OpenAPITransformer();
+  });
+
+  it('transforms schema references', () => {
+    const context: TransformContext = {
+      resourceType: 'endpoint',
+      format: 'openapi',
+    };
+
+    const doc: OpenAPIV3.Document = {
+      openapi: '3.0.0',
+      info: { title: 'Test API', version: '1.0.0' },
+      paths: {},
+      components: {
+        schemas: {
+          Task: {
+            $ref: '#/components/schemas/TaskId',
+          },
+        },
+      },
+    };
+
+    const result = transformer.transformRefs(doc, context);
+    // Expect the new format
+    expect(result.components?.schemas?.Task).toEqual({
+      $ref: 'openapi://components/schemas/TaskId',
+    });
+  });
+
+  it('handles nested references', () => {
+    const context: TransformContext = {
+      resourceType: 'endpoint',
+      format: 'openapi',
+    };
+
+    const doc: OpenAPIV3.Document = {
+      openapi: '3.0.0',
+      info: { title: 'Test API', version: '1.0.0' },
+      paths: {
+        '/tasks': {
+          post: {
+            requestBody: {
+              required: true,
+              description: 'Task creation',
+              content: {
+                'application/json': {
+                  schema: {
+                    $ref: '#/components/schemas/Task',
+                  },
+                },
+              },
+            },
+            responses: {
+              '201': {
+                description: 'Created',
+                content: {
+                  'application/json': {
+                    schema: {
+                      $ref: '#/components/schemas/Task',
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+
+    const result = transformer.transformRefs(doc, context);
+    const taskPath = result.paths?.['/tasks'];
+    expect(taskPath?.post).toBeDefined();
+    const operation = taskPath!.post!;
+    expect(operation.requestBody).toBeDefined();
+    expect('content' in operation.requestBody!).toBeTruthy();
+    const requestBody = operation.requestBody! as OpenAPIV3.RequestBodyObject;
+    expect(requestBody.content?.['application/json']?.schema).toBeDefined();
+    // Expect the new format
+    expect(requestBody.content['application/json'].schema).toEqual({
+      $ref: 'openapi://components/schemas/Task',
+    });
+
+    // Also check the response reference in the same test
+    const response = operation.responses?.['201'];
+    expect(response).toBeDefined();
+    expect('content' in response).toBeTruthy();
+    const responseObj = response as OpenAPIV3.ResponseObject;
+    expect(responseObj.content?.['application/json']?.schema).toBeDefined();
+    // Expect the new format
+    expect(responseObj.content!['application/json'].schema).toEqual({
+      $ref: 'openapi://components/schemas/Task',
+    });
+  });
+
+  it('keeps external references unchanged', () => {
+    const context: TransformContext = {
+      resourceType: 'endpoint',
+      format: 'openapi',
+    };
+
+    const doc: OpenAPIV3.Document = {
+      openapi: '3.0.0',
+      info: { title: 'Test API', version: '1.0.0' },
+      paths: {},
+      components: {
+        schemas: {
+          Task: {
+            $ref: 'https://example.com/schemas/Task',
+          },
+        },
+      },
+    };
+
+    const result = transformer.transformRefs(doc, context);
+    const task = result.components?.schemas?.Task as OpenAPIV3.ReferenceObject;
+    expect(task).toEqual({
+      $ref: 'https://example.com/schemas/Task',
+    });
+  });
+
+  // This test is now invalid as non-schema internal refs *should* be transformed
+  // it('keeps non-schema internal references unchanged', () => { ... });
+
+  it('transforms parameter references', () => {
+    const context: TransformContext = {
+      resourceType: 'endpoint',
+      format: 'openapi',
+    };
+    const doc: OpenAPIV3.Document = {
+      openapi: '3.0.0',
+      info: { title: 'Test API', version: '1.0.0' },
+      paths: {},
+      components: {
+        parameters: {
+          UserIdParam: {
+            $ref: '#/components/parameters/UserId', // Reference another parameter
+          },
+        },
+      },
+    };
+    const result = transformer.transformRefs(doc, context);
+    expect(result.components?.parameters?.UserIdParam).toEqual({
+      $ref: 'openapi://components/parameters/UserId', // Expect transformation
+    });
+  });
+
+  it('transforms response references', () => {
+    const context: TransformContext = {
+      resourceType: 'endpoint',
+      format: 'openapi',
+    };
+    const doc: OpenAPIV3.Document = {
+      openapi: '3.0.0',
+      info: { title: 'Test API', version: '1.0.0' },
+      paths: {},
+      components: {
+        responses: {
+          GenericError: {
+            $ref: '#/components/responses/ErrorModel', // Reference another response
+          },
+        },
+      },
+    };
+    const result = transformer.transformRefs(doc, context);
+    expect(result.components?.responses?.GenericError).toEqual({
+      $ref: 'openapi://components/responses/ErrorModel', // Expect transformation
+    });
+  });
+
+  // Add tests for other component types if needed (examples, requestBodies, etc.)
+
+  it('handles arrays properly', () => {
+    const context: TransformContext = {
+      resourceType: 'endpoint',
+      format: 'openapi',
+    };
+
+    const doc: OpenAPIV3.Document = {
+      openapi: '3.0.0',
+      info: { title: 'Test API', version: '1.0.0' },
+      paths: {},
+      components: {
+        schemas: {
+          TaskList: {
+            type: 'object',
+            properties: {
+              items: {
+                type: 'array',
+                items: {
+                  $ref: '#/components/schemas/Task',
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+
+    const result = transformer.transformRefs(doc, context);
+    const schema = result.components?.schemas?.TaskList;
+    expect(schema).toBeDefined();
+    expect('properties' in schema!).toBeTruthy();
+    const schemaObject = schema! as OpenAPIV3.SchemaObject;
+    expect(schemaObject.properties?.items).toBeDefined();
+    const arraySchema = schemaObject.properties!.items as OpenAPIV3.ArraySchemaObject;
+    // Expect the new format
+    expect(arraySchema.items).toEqual({
+      $ref: 'openapi://components/schemas/Task',
+    });
+  });
+
+  it('preserves non-reference values', () => {
+    const context: TransformContext = {
+      resourceType: 'endpoint',
+      format: 'openapi',
+    };
+
+    const doc: OpenAPIV3.Document = {
+      openapi: '3.0.0',
+      info: {
+        title: 'Test API',
+        version: '1.0.0',
+      },
+      paths: {},
+      components: {
+        schemas: {
+          Test: {
+            type: 'object',
+            properties: {
+              name: { type: 'string' },
+            },
+          },
+        },
+      },
+    };
+
+    const result = transformer.transformRefs(doc, context);
+    expect(result).toEqual(doc);
+  });
+});