import type { OpenAPIV3, OpenAPIV3_1 } from "openapi-types";
// Union type for OpenAPI documents (v3.0 and v3.1)
export type OpenAPIDocument = OpenAPIV3.Document | OpenAPIV3_1.Document;
// Error codes
export type ErrorCode =
| "SPEC_NOT_FOUND"
| "ENDPOINT_NOT_FOUND"
| "PARSE_ERROR"
| "FETCH_ERROR"
| "VALIDATION_ERROR";
// Error response
export interface ErrorResponse {
error: true;
code: ErrorCode;
message: string;
}
// Load tool types
export interface LoadInput {
source: string;
alias: string;
}
export interface LoadResult {
success: boolean;
alias: string;
title: string;
version: string;
endpointCount: number;
tags: string[];
servers?: string[];
}
// List endpoints tool types
export interface ListEndpointsInput {
alias: string;
tag?: string;
search?: string;
}
export interface EndpointSummary {
method: string;
path: string;
operationId: string | null;
summary: string | null;
tags: string[];
deprecated: boolean;
}
export interface ListEndpointsResult {
alias: string;
total: number;
endpoints: EndpointSummary[];
}
// Get endpoint tool types
export interface GetEndpointInput {
alias: string;
method: string;
path: string;
}
export interface ParameterDetail {
name: string;
in: "path" | "query" | "header" | "cookie";
required: boolean;
description: string | null;
schema: Record<string, unknown>;
example: unknown | null;
}
export interface MediaTypeContent {
schema: Record<string, unknown>;
example: unknown | null;
}
export interface RequestBodyDetail {
required: boolean;
description: string | null;
content: Record<string, MediaTypeContent>;
}
export interface ResponseDetail {
description: string;
content: Record<string, MediaTypeContent> | null;
}
export interface EndpointDetail {
method: string;
path: string;
operationId: string | null;
summary: string | null;
description: string | null;
tags: string[];
deprecated: boolean;
parameters: ParameterDetail[];
requestBody: RequestBodyDetail | null;
responses: Record<string, ResponseDetail>;
}
// Helper type guards
export function isOpenAPIV3Document(
doc: unknown
): doc is OpenAPIV3.Document | OpenAPIV3_1.Document {
return (
typeof doc === "object" &&
doc !== null &&
"openapi" in doc &&
typeof (doc as { openapi: unknown }).openapi === "string" &&
(doc as { openapi: string }).openapi.startsWith("3.")
);
}
export function isErrorResponse(obj: unknown): obj is ErrorResponse {
return (
typeof obj === "object" &&
obj !== null &&
"error" in obj &&
(obj as { error: unknown }).error === true
);
}
