Swagger API Documentation Extractor#

Project Overview##

This is a Next.js web application designed to import, view, and extract API documentation from Swagger/OpenAPI specification documents. The application allows users to load Swagger documents through multiple methods and then selectively extract documentation for specific API tags or individual endpoints.

Technical Stack##

• Framework: Next.js 15.2.4 with React 19
• Styling: Tailwind CSS with custom gradients and animations
• UI Components: Radix UI primitives for accessibility
• Icons: Lucide React
• YAML Parsing: js-yaml library
• State Management: React Context API with localStorage persistence
• Theme: next-themes provider (defaulted to light mode)

Core Functionality##

Document Import Methods###

The application provides three ways to import Swagger/OpenAPI documents:

1. File Upload: Drag-and-drop or click-to-browse interface supporting .json, .yaml, and .yml files
2. Copy-Paste: Direct text input for JSON or YAML content
3. URL Import: Fetch documents directly from remote URLs

Document Processing###

• Automatically detects and parses both JSON and YAML formats
• Supports both Swagger 2.0 and OpenAPI 3.0+ specifications
• Extracts and organizes API endpoints by tags
• Generates example request/response payloads from JSON schemas

Viewing Interface###

The application provides two viewing modes:

1. API Explorer: Custom UI that displays:

   • Document metadata (title, version, host, base path)
   • Endpoints organized by tags in expandable sections
   • Method badges with color coding (GET=blue, POST=green, PUT=amber, DELETE=red, etc.)
   • Parameter tables with type information and requirements
   • Request body examples with media type indicators
   • Response schemas with auto-generated examples
   • Status code badges with color coding (2xx=green, 3xx=blue, 4xx=amber, 5xx=red)

2. Raw JSON: Displays the complete imported document as formatted JSON

Extraction and Download Features###

• Tag-level extraction: Download complete API documentation for specific tags, including all related endpoints and schemas
• Individual endpoint extraction: Download documentation for single API endpoints
• Schema dependency resolution: Automatically includes all referenced schemas and nested dependencies
• JSON output: All extractions are provided as formatted JSON files

File Structure and Components##

Core Components###

• FileUploader: Handles all three import methods with loading states and error handling
• SwaggerViewer: Main viewing interface with tabbed layout
• SwaggerDocumentContext: React context provider for document state management
• CustomSwaggerUI: Custom implementation for displaying API documentation

Utility Functions###

• parseSwaggerDocument: Handles JSON/YAML parsing with error handling
• extractApiDocForTag: Creates filtered documentation containing only endpoints with specified tags
• extractApiEndpoint: Extracts documentation for individual endpoints
• collectSchemasFromOperation: Identifies all schema dependencies for operations
• generateExampleFromSchema: Creates example payloads from JSON schema definitions

State Management###

• Uses React Context API for global swagger document state
• Persists imported documents to localStorage for session continuity
• Handles loading states, error states, and toast notifications

Schema Processing###

The application handles complex schema relationships:

• Resolves $ref references to definitions/components
• Processes nested schema dependencies
• Supports allOf, anyOf, oneOf schema compositions
• Handles array items and object properties recursively
• Generates realistic example data from schema definitions

Design Features###

• Responsive design with mobile breakpoint detection
• Gradient backgrounds and modern UI aesthetics
• Smooth animations and transitions
• Hover effects and interactive elements
• Color-coded method and status indicators
• Accessible markup with proper ARIA labels

Data Flow##

1. User imports Swagger document via one of three methods
2. Document is parsed and validated using js-yaml or JSON.parse
3. Document is stored in React context and persisted to localStorage
4. Tags are extracted from document metadata or inferred from endpoint operations
5. Endpoints are grouped by tags and displayed in expandable sections
6. Users can view detailed endpoint information or extract subsets of documentation
7. Extracted documentation includes all necessary schemas and dependencies

Error Handling##

• File format validation for uploads
• JSON/YAML parsing error handling
• Network error handling for URL imports
• Schema reference resolution error handling
• User feedback via toast notifications for all operations

This application serves as a comprehensive tool for API documentation management, allowing developers to work with large Swagger specifications by extracting only the relevant portions they need while maintaining all necessary schema dependencies.