OpenAPI Operation Analyzer

Build a TypeScript utility that analyzes OpenAPI 3.0 operation objects and extracts structured information about their request and response definitions.

Requirements

The utility should provide a function that analyzes a given operation object and extracts structured information about its parameters, request body, and responses. The function should:

1. Extract all parameter definitions from an operation, including their names, locations (query, path, header, cookie), and whether they are required
2. Analyze the request body (if present) and extract the supported media types
3. Extract response definitions for all HTTP status codes, including their descriptions and content types
4. Validate that required fields are present (e.g., response descriptions)
5. Return a structured summary object containing this information

Test Cases

• Given an operation with query and path parameters, it correctly extracts parameter names, locations, and required status @test
• Given an operation with a request body containing JSON and XML media types, it correctly identifies both content types @test
• Given an operation with multiple response codes (200, 400, 404), it extracts all response codes with their descriptions and content types @test
• Given an operation missing a response description, it throws a validation error @test

Implementation

@generates

API

/**
 * Summary of an operation's parameter
 */
export interface ParameterSummary {
  name: string;
  in: 'query' | 'path' | 'header' | 'cookie';
  required: boolean;
}

/**
 * Summary of an operation's request body
 */
export interface RequestBodySummary {
  required: boolean;
  mediaTypes: string[];
}

/**
 * Summary of a single response
 */
export interface ResponseSummary {
  statusCode: string;
  description: string;
  mediaTypes: string[];
}

/**
 * Complete summary of an operation
 */
export interface OperationSummary {
  parameters: ParameterSummary[];
  requestBody?: RequestBodySummary;
  responses: ResponseSummary[];
}

/**
 * Analyzes an OpenAPI 3.0 operation and extracts structured information
 * about its parameters, request body, and responses.
 *
 * @param operation - The OpenAPI 3.0 operation object to analyze
 * @returns A structured summary of the operation
 * @throws Error if the operation has invalid structure (e.g., missing response descriptions)
 */
export function analyzeOperation(operation: any): OperationSummary;

Dependencies { .dependencies }

openapi-types { .dependency }

Provides TypeScript type definitions for OpenAPI 3.0 specifications.

@satisfied-by