@simpleapps-com/augur-api/dist/types/utils/OpenApiSpecParser.d.ts

TypeScript client library for Augur microservices API endpoints

export interface PathInfo {
    path: string;
    methods: string[];
    parameters: string[];
    operationIds: string[];
    hasPathParams: boolean;
    pathParams: string[];
}
export interface Parameter {
    name: string;
    in: 'query' | 'header' | 'path' | 'cookie';
    required?: boolean;
    schema?: Record<string, unknown>;
    description?: string;
}
export interface RequestBody {
    description?: string;
    required?: boolean;
    content?: Record<string, unknown>;
}
export interface Response {
    description: string;
    content?: Record<string, unknown>;
    headers?: Record<string, unknown>;
}
export interface OperationDetails {
    operationId?: string;
    summary?: string;
    description?: string;
    parameters: Parameter[];
    requestBody?: RequestBody;
    responses: Record<string, Response>;
    tags?: string[];
    deprecated?: boolean;
    method: string;
    path: string;
}
export interface SearchResult {
    path: string;
    method: string;
    score: number;
    matchReason: string;
    operation: OperationDetails;
}
export interface ComplexityMetrics {
    totalPaths: number;
    totalEndpoints: number;
    pathsWithParameters: number;
    uniqueParameterCount: number;
    averageMethodsPerPath: number;
    complexityScore: number;
    deprecatedCount: number;
    methodDistribution: Record<string, number>;
}
export interface ValidationResult {
    isValid: boolean;
    errors: string[];
    warnings: string[];
}
export interface ClientStructureInfo {
    path: string;
    clientPath: string[];
    method: string;
    operationId?: string;
    parameters: {
        path: string[];
        query: string[];
        header: string[];
        body?: Record<string, unknown>;
    };
    responseSchema?: Record<string, unknown> | null;
}
/**
 * OpenAPI Specification Parser and Analyzer
 *
 * @fullPath utils.OpenApiSpecParser
 * @service utility
 * @domain openapi-parsing
 * @discoverable true
 * @searchTerms ["openapi", "parse", "specification", "analyze", "validate"]
 * @commonPatterns ["Parse OpenAPI spec", "Analyze API endpoints", "Extract path information"]
 * @workflow ["api-development", "schema-generation", "client-generation"]
 * @prerequisites ["OpenAPI specification file or object"]
 * @nextSteps ["Generate client code", "Create validation schemas", "Analyze API complexity"]
 * @businessRules ["Must validate against OpenAPI 3.0/3.1 specification"]
 * @functionalArea ["api-tooling"]
 * @crossSite ["All microservices with OpenAPI specs"]
 * @caching ["In-memory parsed spec caching"]
 * @performance ["Parse once, query multiple times for best performance"]
 */
interface OpenApiSpec {
    openapi: string;
    info: Record<string, unknown>;
    paths: Record<string, Record<string, unknown>>;
    components?: Record<string, unknown>;
    servers?: Array<Record<string, unknown>>;
}
export declare class OpenApiSpecParser {
    private api;
    private specPath;
    private parsedAt;
    /**
     * Load and parse OpenAPI specification
     *
     * @param source File path, URL, or spec object
     * @returns Parsed OpenAPI Document
     * @throws Error if specification cannot be parsed
     *
     * @example
     * ```typescript
     * const parser = new OpenApiSpecParser();
     * await parser.loadSpec('./openapi/vmi.json');
     * ```
     */
    loadSpec(source: string | Record<string, unknown>): Promise<OpenApiSpec>;
    /**
     * Validate OpenAPI specification against schema
     *
     * @param source File path, URL, or spec object
     * @returns Validation result with errors and warnings
     */
    validateSpec(source?: string | Record<string, unknown>): Promise<ValidationResult>;
    /**
     * Get all API paths with their methods and metadata
     *
     * Replaces: jq -r '.paths | to_entries[] | "\(.key): \(.value | keys | join(", "))"'
     *
     * @returns Array of path information objects
     */
    getAllPaths(): PathInfo[];
    /**
     * Get formatted path list (exact jq replacement)
     *
     * @returns Array of formatted strings like "path: GET, POST"
     */
    getAllPathsFormatted(): string[];
    /**
     * Get total number of paths
     *
     * Replaces: jq '.paths | keys | length'
     *
     * @returns Number of API paths
     */
    getPathCount(): number;
    /**
     * Get total number of endpoints (path + method combinations)
     *
     * @returns Total number of API endpoints
     */
    getEndpointCount(): number;
    /**
     * Get OpenAPI specification info
     *
     * Replaces: jq '.info'
     *
     * @returns OpenAPI info object or null
     */
    getSpecInfo(): Record<string, unknown> | null;
    /**
     * Get server information
     *
     * @returns Array of server definitions
     */
    getServers(): Array<Record<string, unknown>>;
    /**
     * Get detailed information about a specific endpoint
     *
     * @param path API path (e.g., "/users/{id}")
     * @param method HTTP method (e.g., "GET")
     * @returns Operation details or null if not found
     */
    getPathDetails(path: string, method: string): OperationDetails | null;
    /**
     * Get all operation details for all endpoints
     *
     * @returns Array of all operation details
     */
    getAllOperations(): OperationDetails[];
    /**
     * Find deprecated endpoints
     *
     * Replaces complex jq deprecated endpoint queries
     *
     * @returns Array of deprecated endpoint descriptions
     */
    getDeprecatedPaths(): string[];
    /**
     * Search for endpoints by functionality
     *
     * @param searchTerm Term to search for in paths, summaries, descriptions, etc.
     * @returns Array of search results ranked by relevance
     */
    findEndpoints(searchTerm: string): SearchResult[];
    /**
     * Get component schemas
     *
     * @returns Object containing all component schemas
     */
    getComponentSchemas(): Record<string, Record<string, unknown>>;
    /**
     * Get complexity metrics for the API
     *
     * @returns Detailed complexity analysis
     */
    getComplexityMetrics(): ComplexityMetrics;
    /**
     * Generate client structure information for all endpoints
     * This analyzes how each OpenAPI path should map to client method structure
     *
     * @returns Array of client structure mappings
     */
    generateClientStructure(): ClientStructureInfo[];
    /**
     * Validate that the API specification follows expected patterns
     *
     * @returns Validation result with any issues found
     */
    validateSpecification(): ValidationResult;
    /**
     * Get parsing metadata
     *
     * @returns Information about when the spec was parsed
     */
    getParsingInfo(): {
        specPath: string | null;
        parsedAt: Date | null;
        api: boolean;
    };
    private extractMethods;
    private extractPathParameters;
    private extractOperationIds;
    private calculateComplexityScore;
    private pathToClientStructure;
    private toCamelCase;
    private analyzeParameters;
    private extractResponseSchema;
}
/**
 * Factory function for easy usage
 *
 * @returns New OpenApiSpecParser instance
 */
export declare const createOpenApiParser: () => OpenApiSpecParser;
/**
 * Utility function to parse OpenAPI spec from file path
 *
 * @param filePath Path to OpenAPI specification file
 * @returns Configured parser instance
 */
export declare const parseOpenApiSpec: (filePath: string) => Promise<OpenApiSpecParser>;
export {};
//# sourceMappingURL=OpenApiSpecParser.d.ts.map