mcp-openapi-schema-explorer 1.0.0

package/test/__tests__/unit/services/spec-loader.test.ts

@@ -0,0 +1,214 @@
+import { SpecLoaderService } from '../../../../src/services/spec-loader.js';
+import { ReferenceTransformService } from '../../../../src/services/reference-transform.js';
+import { OpenAPIV3 } from 'openapi-types';
+
+// Define mock implementations first
+const mockConvertUrlImplementation = jest.fn();
+const mockConvertFileImplementation = jest.fn();
+
+// Mock the module, referencing the defined implementations
+// IMPORTANT: The factory function for jest.mock runs BEFORE top-level variable assignments in the module scope.
+// We need to access the mocks indirectly.
+interface Swagger2OpenapiResult {
+  openapi: OpenAPIV3.Document;
+  options: unknown; // Use unknown for options as we don't have precise types here
+}
+
+jest.mock('swagger2openapi', () => {
+  // Return an object where the properties are functions that call our mocks
+  return {
+    convertUrl: (url: string, options: unknown): Promise<Swagger2OpenapiResult> =>
+      mockConvertUrlImplementation(url, options) as Promise<Swagger2OpenapiResult>, // Cast return type
+    convertFile: (filename: string, options: unknown): Promise<Swagger2OpenapiResult> =>
+      mockConvertFileImplementation(filename, options) as Promise<Swagger2OpenapiResult>, // Cast return type
+  };
+});
+
+describe('SpecLoaderService', () => {
+  const mockV3Spec: OpenAPIV3.Document = {
+    openapi: '3.0.0',
+    info: {
+      title: 'Test V3 API',
+      version: '1.0.0',
+    },
+    paths: {},
+  };
+
+  // Simulate the structure returned by swagger2openapi
+  const mockS2OResult = {
+    openapi: mockV3Spec,
+    options: {}, // Add other properties if needed by tests
+  };
+
+  let referenceTransform: ReferenceTransformService;
+
+  beforeEach(() => {
+    // Reset the mock implementations
+    mockConvertUrlImplementation.mockReset();
+    mockConvertFileImplementation.mockReset();
+    referenceTransform = new ReferenceTransformService();
+    // Mock the transformDocument method for simplicity in these tests
+    jest.spyOn(referenceTransform, 'transformDocument').mockImplementation(spec => spec);
+  });
+
+  describe('loadSpec', () => {
+    it('loads local v3 spec using convertFile', async () => {
+      mockConvertFileImplementation.mockResolvedValue(mockS2OResult);
+      const loader = new SpecLoaderService('/path/to/spec.json', referenceTransform);
+      const spec = await loader.loadSpec();
+
+      expect(mockConvertFileImplementation).toHaveBeenCalledWith(
+        '/path/to/spec.json',
+        expect.any(Object)
+      );
+      expect(mockConvertUrlImplementation).not.toHaveBeenCalled();
+      expect(spec).toEqual(mockV3Spec);
+    });
+
+    it('loads remote v3 spec using convertUrl', async () => {
+      mockConvertUrlImplementation.mockResolvedValue(mockS2OResult);
+      const loader = new SpecLoaderService('http://example.com/spec.json', referenceTransform);
+      const spec = await loader.loadSpec();
+
+      expect(mockConvertUrlImplementation).toHaveBeenCalledWith(
+        'http://example.com/spec.json',
+        expect.any(Object)
+      );
+      expect(mockConvertFileImplementation).not.toHaveBeenCalled();
+      expect(spec).toEqual(mockV3Spec);
+    });
+
+    it('loads and converts local v2 spec using convertFile', async () => {
+      // Assume convertFile handles v2 internally and returns v3
+      mockConvertFileImplementation.mockResolvedValue(mockS2OResult);
+      const loader = new SpecLoaderService('/path/to/v2spec.json', referenceTransform);
+      const spec = await loader.loadSpec();
+
+      expect(mockConvertFileImplementation).toHaveBeenCalledWith(
+        '/path/to/v2spec.json',
+        expect.any(Object)
+      );
+      expect(mockConvertUrlImplementation).not.toHaveBeenCalled();
+      expect(spec).toEqual(mockV3Spec); // Should be the converted v3 spec
+    });
+
+    it('loads and converts remote v2 spec using convertUrl', async () => {
+      // Assume convertUrl handles v2 internally and returns v3
+      mockConvertUrlImplementation.mockResolvedValue(mockS2OResult);
+      const loader = new SpecLoaderService('https://example.com/v2spec.yaml', referenceTransform);
+      const spec = await loader.loadSpec();
+
+      expect(mockConvertUrlImplementation).toHaveBeenCalledWith(
+        'https://example.com/v2spec.yaml',
+        expect.any(Object)
+      );
+      expect(mockConvertFileImplementation).not.toHaveBeenCalled();
+      expect(spec).toEqual(mockV3Spec); // Should be the converted v3 spec
+    });
+
+    it('throws error if convertFile fails', async () => {
+      const loadError = new Error('File not found');
+      mockConvertFileImplementation.mockRejectedValue(loadError);
+      const loader = new SpecLoaderService('/path/to/spec.json', referenceTransform);
+
+      await expect(loader.loadSpec()).rejects.toThrow(
+        'Failed to load/convert OpenAPI spec from /path/to/spec.json: File not found'
+      );
+    });
+
+    it('throws error if convertUrl fails', async () => {
+      const loadError = new Error('Network error');
+      mockConvertUrlImplementation.mockRejectedValue(loadError);
+      const loader = new SpecLoaderService('http://example.com/spec.json', referenceTransform);
+
+      await expect(loader.loadSpec()).rejects.toThrow(
+        'Failed to load/convert OpenAPI spec from http://example.com/spec.json: Network error'
+      );
+    });
+
+    it('throws error if result object is invalid', async () => {
+      mockConvertFileImplementation.mockResolvedValue({ options: {} }); // Missing openapi property
+      const loader = new SpecLoaderService('/path/to/spec.json', referenceTransform);
+
+      await expect(loader.loadSpec()).rejects.toThrow(
+        'Failed to load/convert OpenAPI spec from /path/to/spec.json: Conversion or parsing failed to produce an OpenAPI document.'
+      );
+    });
+  });
+
+  describe('getSpec', () => {
+    it('returns loaded spec after loadSpec called', async () => {
+      mockConvertFileImplementation.mockResolvedValue(mockS2OResult);
+      const loader = new SpecLoaderService('/path/to/spec.json', referenceTransform);
+      await loader.loadSpec(); // Load first
+      const spec = await loader.getSpec();
+
+      expect(spec).toEqual(mockV3Spec);
+      // Ensure loadSpec was only called once implicitly by the first await
+      expect(mockConvertFileImplementation).toHaveBeenCalledTimes(1);
+    });
+
+    it('loads spec via convertFile if not already loaded', async () => {
+      mockConvertFileImplementation.mockResolvedValue(mockS2OResult);
+      const loader = new SpecLoaderService('/path/to/spec.json', referenceTransform);
+      const spec = await loader.getSpec(); // Should trigger loadSpec
+
+      expect(mockConvertFileImplementation).toHaveBeenCalledWith(
+        '/path/to/spec.json',
+        expect.any(Object)
+      );
+      expect(spec).toEqual(mockV3Spec);
+    });
+
+    it('loads spec via convertUrl if not already loaded', async () => {
+      mockConvertUrlImplementation.mockResolvedValue(mockS2OResult);
+      const loader = new SpecLoaderService('http://example.com/spec.json', referenceTransform);
+      const spec = await loader.getSpec(); // Should trigger loadSpec
+
+      expect(mockConvertUrlImplementation).toHaveBeenCalledWith(
+        'http://example.com/spec.json',
+        expect.any(Object)
+      );
+      expect(spec).toEqual(mockV3Spec);
+    });
+  });
+
+  describe('getTransformedSpec', () => {
+    // Mock the transformer to return a distinctly modified object
+    const mockTransformedSpec = {
+      ...mockV3Spec,
+      info: { ...mockV3Spec.info, title: 'Transformed API' },
+    };
+
+    beforeEach(() => {
+      jest
+        .spyOn(referenceTransform, 'transformDocument')
+        .mockImplementation(() => mockTransformedSpec);
+    });
+
+    it('returns transformed spec after loading', async () => {
+      mockConvertFileImplementation.mockResolvedValue(mockS2OResult);
+      const loader = new SpecLoaderService('/path/to/spec.json', referenceTransform);
+      const spec = await loader.getTransformedSpec({ resourceType: 'endpoint', format: 'openapi' }); // Should load then transform
+
+      expect(mockConvertFileImplementation).toHaveBeenCalledTimes(1); // Ensure loading happened
+      const transformSpy = jest.spyOn(referenceTransform, 'transformDocument');
+      expect(transformSpy).toHaveBeenCalledWith(
+        mockV3Spec,
+        expect.objectContaining({ resourceType: 'endpoint', format: 'openapi' })
+      );
+      expect(spec).toEqual(mockTransformedSpec);
+    });
+
+    it('loads spec if not loaded before transforming', async () => {
+      mockConvertFileImplementation.mockResolvedValue(mockS2OResult);
+      const loader = new SpecLoaderService('/path/to/spec.json', referenceTransform);
+      await loader.getTransformedSpec({ resourceType: 'endpoint', format: 'openapi' }); // Trigger load
+
+      expect(mockConvertFileImplementation).toHaveBeenCalledWith(
+        '/path/to/spec.json',
+        expect.any(Object)
+      );
+    });
+  });
+});

package/test/__tests__/unit/utils/uri-builder.test.ts

@@ -0,0 +1,103 @@
+import {
+  buildComponentDetailUri,
+  buildComponentMapUri,
+  buildOperationUri,
+  buildPathItemUri,
+  buildTopLevelFieldUri,
+  buildComponentDetailUriSuffix,
+  buildComponentMapUriSuffix,
+  buildOperationUriSuffix,
+  buildPathItemUriSuffix,
+  buildTopLevelFieldUriSuffix,
+} from '../../../../src/utils/uri-builder';
+
+describe('URI Builder Utilities', () => {
+  // --- Full URI Builders ---
+
+  test('buildComponentDetailUri builds correct URI', () => {
+    expect(buildComponentDetailUri('schemas', 'MySchema')).toBe(
+      'openapi://components/schemas/MySchema'
+    );
+    expect(buildComponentDetailUri('responses', 'NotFound')).toBe(
+      'openapi://components/responses/NotFound'
+    );
+    // Test with characters that might need encoding if rules change (but currently don't)
+    expect(buildComponentDetailUri('parameters', 'user-id')).toBe(
+      'openapi://components/parameters/user-id'
+    );
+  });
+
+  test('buildComponentMapUri builds correct URI', () => {
+    expect(buildComponentMapUri('schemas')).toBe('openapi://components/schemas');
+    expect(buildComponentMapUri('parameters')).toBe('openapi://components/parameters');
+  });
+
+  test('buildOperationUri builds correct URI and encodes path (no leading slash)', () => {
+    expect(buildOperationUri('/users', 'get')).toBe('openapi://paths/users/get'); // No leading slash encoded
+    expect(buildOperationUri('/users/{userId}', 'post')).toBe(
+      'openapi://paths/users%2F%7BuserId%7D/post' // Path encoded, no leading %2F
+    );
+    expect(buildOperationUri('/pets/{petId}/uploadImage', 'post')).toBe(
+      'openapi://paths/pets%2F%7BpetId%7D%2FuploadImage/post' // Path encoded, no leading %2F
+    );
+    expect(buildOperationUri('users', 'get')).toBe('openapi://paths/users/get'); // Handles no leading slash input
+    expect(buildOperationUri('users/{userId}', 'post')).toBe(
+      'openapi://paths/users%2F%7BuserId%7D/post' // Handles no leading slash input
+    );
+    expect(buildOperationUri('/users', 'GET')).toBe('openapi://paths/users/get'); // Method lowercased
+  });
+
+  test('buildPathItemUri builds correct URI and encodes path (no leading slash)', () => {
+    expect(buildPathItemUri('/users')).toBe('openapi://paths/users'); // No leading slash encoded
+    expect(buildPathItemUri('/users/{userId}')).toBe('openapi://paths/users%2F%7BuserId%7D'); // Path encoded, no leading %2F
+    expect(buildPathItemUri('/pets/{petId}/uploadImage')).toBe(
+      'openapi://paths/pets%2F%7BpetId%7D%2FuploadImage' // Path encoded, no leading %2F
+    );
+    expect(buildPathItemUri('users')).toBe('openapi://paths/users'); // Handles no leading slash input
+    expect(buildPathItemUri('users/{userId}')).toBe('openapi://paths/users%2F%7BuserId%7D'); // Handles no leading slash input
+  });
+
+  test('buildTopLevelFieldUri builds correct URI', () => {
+    expect(buildTopLevelFieldUri('info')).toBe('openapi://info');
+    expect(buildTopLevelFieldUri('paths')).toBe('openapi://paths');
+    expect(buildTopLevelFieldUri('components')).toBe('openapi://components');
+  });
+
+  // --- URI Suffix Builders ---
+
+  test('buildComponentDetailUriSuffix builds correct suffix', () => {
+    expect(buildComponentDetailUriSuffix('schemas', 'MySchema')).toBe(
+      'components/schemas/MySchema'
+    );
+    expect(buildComponentDetailUriSuffix('responses', 'NotFound')).toBe(
+      'components/responses/NotFound'
+    );
+  });
+
+  test('buildComponentMapUriSuffix builds correct suffix', () => {
+    expect(buildComponentMapUriSuffix('schemas')).toBe('components/schemas');
+    expect(buildComponentMapUriSuffix('parameters')).toBe('components/parameters');
+  });
+
+  test('buildOperationUriSuffix builds correct suffix and encodes path (no leading slash)', () => {
+    expect(buildOperationUriSuffix('/users', 'get')).toBe('paths/users/get'); // No leading slash encoded
+    expect(buildOperationUriSuffix('/users/{userId}', 'post')).toBe(
+      'paths/users%2F%7BuserId%7D/post' // Path encoded, no leading %2F
+    );
+    expect(buildOperationUriSuffix('users/{userId}', 'post')).toBe(
+      'paths/users%2F%7BuserId%7D/post' // Handles no leading slash input
+    );
+    expect(buildOperationUriSuffix('/users', 'GET')).toBe('paths/users/get'); // Method lowercased
+  });
+
+  test('buildPathItemUriSuffix builds correct suffix and encodes path (no leading slash)', () => {
+    expect(buildPathItemUriSuffix('/users')).toBe('paths/users'); // No leading slash encoded
+    expect(buildPathItemUriSuffix('/users/{userId}')).toBe('paths/users%2F%7BuserId%7D'); // Path encoded, no leading %2F
+    expect(buildPathItemUriSuffix('users/{userId}')).toBe('paths/users%2F%7BuserId%7D'); // Handles no leading slash input
+  });
+
+  test('buildTopLevelFieldUriSuffix builds correct suffix', () => {
+    expect(buildTopLevelFieldUriSuffix('info')).toBe('info');
+    expect(buildTopLevelFieldUriSuffix('paths')).toBe('paths');
+  });
+});

package/test/fixtures/complex-endpoint.json

@@ -0,0 +1,146 @@
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "Complex Endpoint Test API",
+    "version": "1.0.0"
+  },
+  "paths": {
+    "/api/v1/organizations/{orgId}/projects/{projectId}/tasks": {
+      "get": {
+        "operationId": "getProjectTasks",
+        "summary": "Get Tasks",
+        "description": "Retrieve a list of tasks for a specific project.",
+        "parameters": [
+          {
+            "name": "orgId",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "string" }
+          },
+          {
+            "name": "projectId",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "string" }
+          },
+          {
+            "name": "status",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "enum": ["active", "completed"]
+            }
+          },
+          {
+            "name": "sort",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "enum": ["created", "updated", "priority"]
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "List of tasks",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/TaskList"
+                }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "operationId": "createProjectTask",
+        "summary": "Create Task",
+        "description": "Create a new task within a project.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateTaskRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Task created",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Task"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "Task": {
+        "type": "object",
+        "required": ["id", "title", "status"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "title": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["active", "completed"]
+          },
+          "priority": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 5
+          }
+        }
+      },
+      "TaskList": {
+        "type": "object",
+        "required": ["items"],
+        "properties": {
+          "items": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Task"
+            }
+          },
+          "totalCount": {
+            "type": "integer"
+          }
+        }
+      },
+      "CreateTaskRequest": {
+        "type": "object",
+        "required": ["title"],
+        "properties": {
+          "title": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["active", "completed"],
+            "default": "active"
+          },
+          "priority": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 5,
+            "default": 3
+          }
+        }
+      }
+    }
+  }
+}

package/test/fixtures/empty-api.json

@@ -0,0 +1,8 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "Empty API",
+    "version": "1.0.0"
+  },
+  "paths": {}
+}

package/test/fixtures/multi-component-types.json

@@ -0,0 +1,55 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "Multi Component Type Test API",
+    "version": "1.0.0"
+  },
+  "paths": {
+    "/ping": {
+      "get": {
+        "summary": "Ping",
+        "operationId": "ping",
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Pong"
+                }
+              }
+            }
+          }
+        },
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/TraceId"
+          }
+        ]
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "Pong": {
+        "type": "object",
+        "properties": {
+          "message": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "parameters": {
+      "TraceId": {
+        "name": "X-Trace-ID",
+        "in": "header",
+        "required": false,
+        "schema": {
+          "type": "string",
+          "format": "uuid"
+        }
+      }
+    }
+  }
+}

package/test/fixtures/paths-test.json

@@ -0,0 +1,61 @@
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "Path Testing API",
+    "version": "1.0.0"
+  },
+  "paths": {
+    "/project/tasks/{taskId}": {
+      "get": {
+        "summary": "Get task details",
+        "parameters": [
+          {
+            "name": "taskId",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "string" }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Task details"
+          }
+        }
+      }
+    },
+    "/article/{articleId}/comment/{commentId}": {
+      "get": {
+        "summary": "Get comment on article",
+        "parameters": [
+          {
+            "name": "articleId",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "string" }
+          },
+          {
+            "name": "commentId",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "string" }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Comment details"
+          }
+        }
+      }
+    },
+    "/sub/sub/sub/sub/folded/entrypoint": {
+      "post": {
+        "summary": "Deeply nested endpoint",
+        "responses": {
+          "201": {
+            "description": "Created"
+          }
+        }
+      }
+    }
+  }
+}

package/test/fixtures/sample-api.json

@@ -0,0 +1,68 @@
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "Sample API",
+    "version": "1.0.0"
+  },
+  "paths": {
+    "/users": {
+      "get": {
+        "summary": "List users",
+        "operationId": "listUsers",
+        "responses": {
+          "200": {
+            "description": "List of users",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UserList"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "User": {
+        "type": "object",
+        "required": ["id", "email"],
+        "properties": {
+          "id": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "email": {
+            "type": "string",
+            "format": "email"
+          },
+          "name": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["active", "inactive"]
+          }
+        }
+      },
+      "UserList": {
+        "type": "object",
+        "required": ["users"],
+        "properties": {
+          "users": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/User"
+            }
+          },
+          "total": {
+            "type": "integer",
+            "format": "int32"
+          }
+        }
+      }
+    }
+  }
+}