Add DocC generators, CLI, Integration, and build scripts

Author: ayushshrivastv

Package.swift

@@ -17,6 +17,9 @@ let package = Package(
         .executable(
             name: "openapi-to-symbolgraph",
             targets: ["CLI"]),
+        .executable(
+            name: "symbol-graph-debug",
+            targets: ["SymbolGraphDebug"]),
     ],
     dependencies: [
         .package(url: "https://github.com/jpsim/Yams.git", from: "5.0.6"),
@@ -83,6 +86,15 @@ let package = Package(
             path: "Sources/CLI",
             exclude: ["README.md"]
         ),
+        .executableTarget(
+            name: "SymbolGraphDebug",
+            dependencies: [
+                "OpenAPItoSymbolGraph",
+                .product(name: "ArgumentParser", package: "swift-argument-parser"),
+                .product(name: "SymbolKit", package: "swift-docc-symbolkit")
+            ],
+            path: "Sources/SymbolGraphDebug"
+        ),
         .testTarget(
             name: "OpenAPItoSymbolGraphTests",
             dependencies: [

Sources/CLI/main.swift

@@ -20,6 +20,9 @@ struct OpenAPIToSymbolGraph: ParsableCommand {
     @Option(name: .long, help: "Name to use for the module in the symbol graph", transform: { $0 })
     var moduleName: String?
 
+    @Option(name: .long, help: "Base URL of the API for HTTP endpoint documentation", transform: { URL(string: $0) })
+    var baseURL: URL?
+    
     mutating func run() throws {
         // Check file extension
         let fileExtension = URL(fileURLWithPath: inputPath).pathExtension.lowercased()
@@ -40,7 +43,7 @@ struct OpenAPIToSymbolGraph: ParsableCommand {
             let document = try parser.parse(fileContent)
 
             // Convert to symbol graph
-            let converter = Integration.OpenAPIDocCConverter(moduleName: moduleName)
+            let converter = Integration.OpenAPIDocCConverter(moduleName: moduleName, baseURL: baseURL)
             let symbolGraph = converter.convert(document)
 
             // Write the symbol graph to file

Sources/DocC/Generators/HTTPMixins.swift

@@ -0,0 +1,77 @@
+import Foundation
+import SymbolKit
+import OpenAPI
+
+// Custom HTTP mixins implementation that follows SymbolKit pattern
+extension SymbolKit.SymbolGraph.Symbol {
+    /// Namespace for HTTP-specific mixins
+    public enum HTTP {
+        /// Mixin key for HTTP endpoint information
+        public static let endpointMixinKey = "httpEndpoint"
+        
+        /// Mixin key for HTTP parameter source information
+        public static let parameterSourceMixinKey = "httpParameterSource"
+        
+        /// Mixin key for HTTP media type information
+        public static let mediaTypeMixinKey = "httpMediaType"
+        
+        /// The HTTP endpoint for a request.
+        public struct Endpoint: Codable, SymbolKit.Mixin {
+            public static let mixinKey = endpointMixinKey
+            
+            /// The HTTP method of the request (e.g., GET, POST, PUT, DELETE).
+            /// The value is always uppercased.
+            public var method: String
+            
+            /// The base URL of the request.
+            public var baseURL: URL
+            
+            /// The alternate base URL of the request when used within a test environment.
+            public var sandboxURL: URL?
+            
+            /// The relative path specific to the endpoint.
+            public var path: String
+            
+            public init(method: String, baseURL: URL, sandboxURL: URL? = nil, path: String) {
+                self.method = method.uppercased()
+                self.baseURL = baseURL
+                self.sandboxURL = sandboxURL
+                self.path = path
+            }
+        }
+        
+        /// The source location of an HTTP parameter.
+        public struct ParameterSource: Codable, SymbolKit.Mixin {
+            public static let mixinKey = parameterSourceMixinKey
+            
+            /// The parameter source location (path, query, header, or cookie)
+            public var value: String
+            
+            public init(_ value: String) {
+                self.value = value
+            }
+            
+            public init(_ location: ParameterLocation) {
+                self.value = location.rawValue
+            }
+        }
+        
+        /// The encoding media type for an HTTP payload.
+        public struct MediaType: Codable, SymbolKit.Mixin {
+            public static let mixinKey = mediaTypeMixinKey
+            
+            /// The media type (e.g., "application/json")
+            public var value: String
+            
+            public init(_ value: String) {
+                self.value = value
+            }
+        }
+    }
+}
+
+/// Protocol for SymbolKit mixins to ensure consistency
+public protocol Mixin: Encodable {
+    /// The key used to identify this mixin in a symbol's mixins dictionary
+    static var mixinKey: String { get }
+} 

Sources/DocC/Generators/SymbolGraphGenerator.swift

@@ -6,16 +6,22 @@ import SymbolKit
 public struct SymbolGraphGenerator {
     /// The name to use for the module
     public var moduleName: String?
+    /// Base URL for the API
+    public var baseURL: URL?
 
     /// Creates a new symbol graph generator
-    public init(moduleName: String? = nil) {
+    public init(moduleName: String? = nil, baseURL: URL? = nil) {
         self.moduleName = moduleName
+        self.baseURL = baseURL
     }
 
     /// Generates a symbol graph from an OpenAPI document
     /// - Parameter document: The OpenAPI document to convert
     /// - Returns: The generated symbol graph
     public func generate(from document: Document) -> SymbolKit.SymbolGraph {
+        // For now, we'll skip the mixin registration as it requires more work to implement correctly
+        // We're still generating valid symbol graphs, just without the HTTP-specific enhancements
+        
         var symbols: [SymbolKit.SymbolGraph.Symbol] = []
         var relationships: [SymbolKit.SymbolGraph.Relationship] = []
 
@@ -187,14 +193,27 @@ public struct SymbolGraphGenerator {
             docComment = SymbolKit.SymbolGraph.LineList([line])
         }
 
+        // Create mixins for HTTP endpoint
+        var mixins: [String: SymbolKit.Mixin] = [:]
+        
+        // Add HTTP endpoint mixin if baseURL is provided
+        if let baseURL = self.baseURL {
+            let httpEndpoint = SymbolKit.SymbolGraph.Symbol.HTTP.Endpoint(
+                method: method.rawValue,
+                baseURL: baseURL,
+                path: path
+            )
+            mixins[SymbolKit.SymbolGraph.Symbol.HTTP.endpointMixinKey] = httpEndpoint
+        }
+        
         return SymbolKit.SymbolGraph.Symbol(
             identifier: identifier,
             names: names,
             pathComponents: [path, method.rawValue],
             docComment: docComment,
             accessLevel: SymbolKit.SymbolGraph.Symbol.AccessControl(rawValue: "public"),
             kind: .init(parsedIdentifier: .method, displayName: "Operation"),
-            mixins: [:]
+            mixins: mixins
         )
     }
 
@@ -218,14 +237,21 @@ public struct SymbolGraphGenerator {
             docComment = SymbolKit.SymbolGraph.LineList([line])
         }
 
+        // Create mixins for HTTP parameter
+        var mixins: [String: SymbolKit.Mixin] = [:]
+        
+        // Add HTTP parameter source mixin
+        let httpParameterSource = SymbolKit.SymbolGraph.Symbol.HTTP.ParameterSource(parameter.in)
+        mixins[SymbolKit.SymbolGraph.Symbol.HTTP.parameterSourceMixinKey] = httpParameterSource
+        
         return SymbolKit.SymbolGraph.Symbol(
             identifier: identifier,
             names: names,
             pathComponents: operation.pathComponents + [parameter.name],
             docComment: docComment,
             accessLevel: SymbolKit.SymbolGraph.Symbol.AccessControl(rawValue: "public"),
             kind: .init(parsedIdentifier: .property, displayName: "Parameter"),
-            mixins: [:]
+            mixins: mixins
         )
     }
 
@@ -247,14 +273,23 @@ public struct SymbolGraphGenerator {
         let line = SymbolKit.SymbolGraph.LineList.Line(text: response.description, range: nil)
         let docComment = SymbolKit.SymbolGraph.LineList([line])
 
+        // Create mixins for HTTP response
+        var mixins: [String: SymbolKit.Mixin] = [:]
+        
+        // Add HTTP media type mixin if content is available
+        if let content = response.content?.first {
+            let mediaType = SymbolKit.SymbolGraph.Symbol.HTTP.MediaType(content.key)
+            mixins[SymbolKit.SymbolGraph.Symbol.HTTP.mediaTypeMixinKey] = mediaType
+        }
+        
         return SymbolKit.SymbolGraph.Symbol(
             identifier: identifier,
             names: names,
             pathComponents: operation.pathComponents + [statusCode],
             docComment: docComment,
             accessLevel: SymbolKit.SymbolGraph.Symbol.AccessControl(rawValue: "public"),
             kind: .init(parsedIdentifier: .struct, displayName: "Response"),
-            mixins: [:]
+            mixins: mixins
         )
     }
 

Sources/Integration/OpenAPIDocCConverter.swift

@@ -7,17 +7,20 @@ import SymbolKit
 public struct OpenAPIDocCConverter {
     /// The name to use for the module
     private let moduleName: String?
+    /// Base URL for the API
+    private let baseURL: URL?
 
     /// Creates a new OpenAPI to DocC converter
-    public init(moduleName: String? = nil) {
+    public init(moduleName: String? = nil, baseURL: URL? = nil) {
         self.moduleName = moduleName
+        self.baseURL = baseURL
     }
 
     /// Converts an OpenAPI document to a DocC symbol graph
     /// - Parameter document: The OpenAPI document to convert
     /// - Returns: The DocC symbol graph
     public func convert(_ document: Document) -> SymbolKit.SymbolGraph {
-        let generator = SymbolGraphGenerator(moduleName: moduleName)
+        let generator = SymbolGraphGenerator(moduleName: moduleName, baseURL: baseURL)
         return generator.generate(from: document)
     }
 }

Sources/SymbolGraphDebug/README.md

@@ -0,0 +1,62 @@
+# Symbol Graph Debug Tool
+
+This tool helps debug and analyze DocC symbol graphs generated from OpenAPI specifications. It provides several commands to help you understand the structure of your symbol graphs and identify issues.
+
+## Usage
+
+```
+swift run symbol-graph-debug [command] [options]
+```
+
+### Commands
+
+- **analyze**: Performs a comprehensive analysis of a symbol graph
+- **validate-relationships**: Validates all relationships in a symbol graph
+- **show-symbol**: Shows detailed information about a specific symbol
+- **show-http**: Shows HTTP-specific information for API endpoints
+
+## Findings
+
+Through our investigation using this tool, we've identified several insights about the OpenAPI integration with DocC:
+
+1. **Symbol Graph Structure**: The OpenAPI to Symbol Graph conversion is generating valid symbol graphs with correct relationships.
+
+2. **HTTP Mixins**: SymbolKit provides HTTP-specific mixins that can enhance API documentation with endpoint details, parameter sources, and media types. 
+
+3. **DocC Integration Challenges**:
+   - DocC doesn't seem to fully render symbols from the OpenAPI interface language
+   - Child symbols aren't appearing in the `topicSections` array of the module JSON
+   - This suggests DocC may not be properly associating or recognizing these symbols
+
+4. **Module Name Consistency**: It's critical to ensure the module name is consistent between:
+   - The symbol graph's `module.name` value
+   - The DocC documentation target
+   - Path components in symbols
+
+5. **Relationship Structure**: The relationship structure is valid but might need adjustments to be fully recognized by DocC.
+
+## Potential Solutions
+
+1. **Interface Language**: Consider using "swift" as the interface language instead of "openapi" to potentially improve DocC compatibility.
+
+2. **HTTP Mixins**: Fully implement HTTP mixins to enhance REST API documentation.
+
+3. **Symbol Registration**: Implement proper symbol registration for mixins to enable DocC to recognize and utilize HTTP-specific information.
+
+4. **DocC Extensions**: Consider creating DocC extensions specifically for OpenAPI types to improve rendering.
+
+## Example Usage
+
+```bash
+# Analyze a symbol graph
+.build/debug/symbol-graph-debug analyze registry.symbolgraph.json
+
+# Validate relationships
+.build/debug/symbol-graph-debug validate-relationships registry.symbolgraph.json
+
+# Show HTTP endpoints
+.build/debug/symbol-graph-debug show-http registry.symbolgraph.json
+
+# Show details of a specific symbol
+.build/debug/symbol-graph-debug show-symbol registry.symbolgraph.json "module"
+```