Add OpenAPI to DocC converter implementation and tests

Author: ayushshrivastv

Documentation/Guides/AdvancedTopics.md

@@ -0,0 +1,124 @@
+# Advanced Topics
+
+## Custom Templates
+
+### Creating Custom Templates
+You can create custom documentation templates by extending the base template system:
+
+```swift
+struct CustomTemplate: DocumentationTemplate {
+    func render(symbol: Symbol) -> String {
+        // Custom rendering logic
+    }
+}
+```
+
+### Template Configuration
+Configure templates in your `config.json`:
+
+```json
+{
+    "templates": {
+        "default": "path/to/custom/template",
+        "custom": {
+            "style": "dark",
+            "layout": "sidebar"
+        }
+    }
+}
+```
+
+## Advanced Symbol Generation
+
+### Custom Symbol Mappings
+Override default symbol mappings:
+
+```swift
+struct CustomSymbolMapper: SymbolMapper {
+    func map(openAPIComponent: OpenAPIComponent) -> Symbol {
+        // Custom mapping logic
+    }
+}
+```
+
+### Symbol Relationships
+Define custom relationships between symbols:
+
+```swift
+struct CustomRelationshipGenerator: RelationshipGenerator {
+    func generateRelationships(symbols: [Symbol]) -> [Relationship] {
+        // Custom relationship generation
+    }
+}
+```
+
+## Performance Optimization
+
+### Caching
+Enable caching for improved performance:
+
+```json
+{
+    "cache": {
+        "enabled": true,
+        "directory": ".cache",
+        "ttl": 3600
+    }
+}
+```
+
+### Parallel Processing
+Configure parallel processing options:
+
+```json
+{
+    "processing": {
+        "maxConcurrent": 4,
+        "chunkSize": 100
+    }
+}
+```
+
+## Integration with Build Systems
+
+### Xcode Integration
+Add a build phase to your Xcode project:
+
+```bash
+openapi-to-symbolgraph "${SRCROOT}/path/to/openapi.yaml" --output "${BUILT_PRODUCTS_DIR}/Documentation"
+```
+
+### CI/CD Integration
+Example GitHub Actions workflow:
+
+```yaml
+name: Generate Documentation
+on: [push, pull_request]
+jobs:
+  build:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Generate Docs
+        run: |
+          swift run openapi-to-symbolgraph api.yaml
+```
+
+## Troubleshooting
+
+### Common Issues
+- **Memory Usage**: Adjust chunk size for large documents
+- **Performance**: Enable caching for repeated builds
+- **Template Errors**: Check template syntax and validation
+
+### Debugging
+Enable debug logging:
+
+```bash
+openapi-to-symbolgraph api.yaml --verbose --debug
+```
+
+## Next Steps
+- Explore the [API Reference](APIReference.md)
+- Check out [Advanced Tutorials](Tutorial2.md)
+- Review [Best Practices](../Reference/BestPractices.md) 

Documentation/Guides/GettingStarted.md

@@ -0,0 +1,64 @@
+# Getting Started with OpenAPI-DocC Integration
+
+## Installation
+
+### Using Swift Package Manager
+Add the following to your `Package.swift` file:
+
+```swift
+dependencies: [
+    .package(url: "https://github.com/yourusername/OpenAPI-DocC-Integration.git", from: "1.0.0")
+]
+```
+
+### Manual Installation
+1. Clone the repository:
+```bash
+git clone https://github.com/yourusername/OpenAPI-DocC-Integration.git
+```
+2. Build the package:
+```bash
+swift build
+```
+
+## Basic Usage
+
+### Command Line Interface
+The simplest way to use the tool is through the command line:
+
+```bash
+openapi-to-symbolgraph path/to/your/openapi.yaml
+```
+
+This will generate a DocC-compatible symbol graph file.
+
+### Programmatic Usage
+You can also use the library programmatically:
+
+```swift
+import OpenAPIDocC
+
+let converter = OpenAPIDocCConverter()
+let symbolGraph = try converter.convert(openAPIFile: "path/to/your/openapi.yaml")
+```
+
+## Configuration
+
+### Basic Configuration
+Create a `config.json` file in your project root:
+
+```json
+{
+    "outputPath": "docs",
+    "template": "default",
+    "includeExamples": true
+}
+```
+
+### Advanced Configuration
+See [Advanced Topics](AdvancedTopics.md) for more configuration options.
+
+## Next Steps
+- Try the [Basic Tutorial](Tutorial1.md)
+- Explore [Advanced Features](AdvancedTopics.md)
+- Check the [API Reference](APIReference.md) 

Documentation/Guides/Introduction.md

@@ -0,0 +1,27 @@
+# Introduction to OpenAPI-DocC Integration
+
+## Overview
+The OpenAPI-DocC Integration project provides a seamless way to generate DocC documentation from OpenAPI specifications. This tool bridges the gap between OpenAPI's comprehensive API description format and DocC's powerful documentation capabilities in the Swift ecosystem.
+
+## Key Features
+- Convert OpenAPI documents (YAML/JSON) to DocC-compatible symbol graphs
+- Generate comprehensive API documentation
+- Support for OpenAPI 3.0 and 3.1 specifications
+- Customizable documentation templates
+- Integration with existing DocC workflows
+
+## Why Use This Tool?
+- **Consistency**: Maintain a single source of truth for your API documentation
+- **Developer Experience**: Leverage familiar DocC documentation in Xcode
+- **Automation**: Automate documentation generation as part of your build process
+- **Rich Documentation**: Combine OpenAPI's API description with DocC's rich documentation features
+
+## Prerequisites
+- Swift 5.7 or later
+- Xcode 14 or later (for DocC integration)
+- Basic understanding of OpenAPI specifications
+- Familiarity with Swift and DocC documentation
+
+## Next Steps
+- [Getting Started](GettingStarted.md)
+- [Advanced Topics](AdvancedTopics.md) 

Documentation/Reference/APIReference.md

@@ -0,0 +1,176 @@
+# API Reference
+
+## Core Types
+
+### OpenAPIDocCConverter
+
+The main converter class that handles the conversion from OpenAPI to DocC.
+
+```swift
+public class OpenAPIDocCConverter {
+    public init(configuration: Configuration = .default)
+    public func convert(openAPIFile: String) throws -> SymbolGraph
+    public func convert(openAPIData: Data, fileExtension: String) throws -> SymbolGraph
+}
+```
+
+### Configuration
+
+Configuration options for the converter.
+
+```swift
+public struct Configuration {
+    public var outputPath: String
+    public var template: Template
+    public var cache: CacheConfiguration
+    public var processing: ProcessingConfiguration
+    
+    public static var `default`: Configuration
+}
+```
+
+## Templates
+
+### DocumentationTemplate
+
+Protocol for custom documentation templates.
+
+```swift
+public protocol DocumentationTemplate {
+    func render(symbol: Symbol) -> String
+}
+```
+
+### DefaultTemplate
+
+The default template implementation.
+
+```swift
+public struct DefaultTemplate: DocumentationTemplate {
+    public init()
+    public func render(symbol: Symbol) -> String
+}
+```
+
+## Symbol Mapping
+
+### SymbolMapper
+
+Protocol for custom symbol mapping.
+
+```swift
+public protocol SymbolMapper {
+    func map(openAPIComponent: OpenAPIComponent) -> Symbol
+}
+```
+
+### DefaultSymbolMapper
+
+The default symbol mapper implementation.
+
+```swift
+public struct DefaultSymbolMapper: SymbolMapper {
+    public init()
+    public func map(openAPIComponent: OpenAPIComponent) -> Symbol
+}
+```
+
+## Utilities
+
+### URLTemplate
+
+Utility for handling URL templates in OpenAPI specifications.
+
+```swift
+public struct URLTemplate {
+    public init(template: String)
+    public func expand(parameters: [String: String]) -> String
+}
+```
+
+### Validation
+
+Utility for validating OpenAPI specifications.
+
+```swift
+public struct Validation {
+    public static func validate(_ document: OpenAPI.Document) throws
+    public static func validate(_ schema: JSONSchema) throws
+}
+```
+
+## Error Types
+
+### ConversionError
+
+Errors that can occur during conversion.
+
+```swift
+public enum ConversionError: Error {
+    case invalidFileType(String)
+    case parsingError(String)
+    case validationError(String)
+    case templateError(String)
+}
+```
+
+## Configuration Types
+
+### CacheConfiguration
+
+Configuration for caching.
+
+```swift
+public struct CacheConfiguration {
+    public var enabled: Bool
+    public var directory: String
+    public var ttl: TimeInterval
+}
+```
+
+### ProcessingConfiguration
+
+Configuration for parallel processing.
+
+```swift
+public struct ProcessingConfiguration {
+    public var maxConcurrent: Int
+    public var chunkSize: Int
+}
+```
+
+## Usage Examples
+
+### Basic Conversion
+
+```swift
+let converter = OpenAPIDocCConverter()
+let symbolGraph = try converter.convert(openAPIFile: "api.yaml")
+```
+
+### Custom Configuration
+
+```swift
+var config = Configuration.default
+config.outputPath = "custom/docs"
+config.template = CustomTemplate()
+let converter = OpenAPIDocCConverter(configuration: config)
+```
+
+### Custom Symbol Mapping
+
+```swift
+struct CustomMapper: SymbolMapper {
+    func map(openAPIComponent: OpenAPIComponent) -> Symbol {
+        // Custom mapping logic
+    }
+}
+
+let converter = OpenAPIDocCConverter()
+converter.symbolMapper = CustomMapper()
+```
+
+## Related Documentation
+- [Data Types](DataTypes.md)
+- [Best Practices](BestPractices.md)
+- [Advanced Topics](../Guides/AdvancedTopics.md)