Refactor: Organize project structure and fix build issues

Author: ayushshrivastv

Package.swift

@@ -17,28 +17,54 @@ let package = Package(
         .package(url: "https://github.com/jpsim/Yams.git", from: "5.0.0"),
     ],
     targets: [
+        // Core functionality
         .target(
             name: "Core",
             dependencies: [
                 .product(name: "OpenAPIKit", package: "OpenAPIKit"),
                 .product(name: "SymbolKit", package: "swift-docc-symbolkit")
             ],
-            path: "Sources/Core"
+            path: "Sources/Core",
+            exclude: ["README.md"]
         ),
+        
+        // CLI executable
         .executableTarget(
             name: "CLI",
             dependencies: [
                 "Core",
+                "OpenAPItoSymbolGraph",
                 .product(name: "ArgumentParser", package: "swift-argument-parser"),
                 .product(name: "Yams", package: "Yams"),
                 .product(name: "OpenAPIKit", package: "OpenAPIKit"),
                 .product(name: "SymbolKit", package: "swift-docc-symbolkit")
             ],
-            path: "Sources/CLI"
+            path: "Sources/CLI",
+            exclude: ["README.md"]
         ),
+        
+        // OpenAPItoSymbolGraph main framework
+        .target(
+            name: "OpenAPItoSymbolGraph",
+            dependencies: [
+                "Core",
+                .product(name: "SymbolKit", package: "swift-docc-symbolkit"),
+                .product(name: "OpenAPIKit", package: "OpenAPIKit"),
+                .product(name: "Yams", package: "Yams")
+            ],
+            path: "Sources/OpenAPItoSymbolGraph",
+            exclude: [
+                "README.md",
+                "Utils/README.md", 
+                "Utils/DocC/README.md",
+                "Mapping/README.md"
+            ]
+        ),
+        
+        // Tests
         .testTarget(
             name: "OpenAPItoSymbolGraphTests",
-            dependencies: ["Core", "CLI"],
+            dependencies: ["Core", "CLI", "OpenAPItoSymbolGraph"],
             path: "Tests"
         )
     ]

README.md

@@ -13,6 +13,16 @@ OpenAPI is the industry standard for documenting HTTP services, but Swift develo
 - Provide a consistent documentation experience for Swift developers
 - Support for documenting endpoints, schemas, parameters, and more
 
+## Project Structure
+
+The project is organized into several modules:
+
+- `Sources/Core` - Core functionality and data models
+- `Sources/CLI` - Command-line interface 
+- `Sources/OpenAPItoSymbolGraph` - Main implementation with submodules:
+  - `Mapping` - Mappers between OpenAPI and SymbolGraph
+  - `Utils/DocC` - DocC integration utilities
+
 ## Getting Started
 
 ### Prerequisites
@@ -34,7 +44,20 @@ swift build
 1. Convert your OpenAPI specification to a SymbolGraph:
 
 ```bash
-swift run openapi-to-symbolgraph path/to/your/api.yaml --output-path api.symbolgraph.json
+# Example using one of the provided files
+swift run openapi-to-symbolgraph Examples/api.yaml --output-path api.symbolgraph.json
+```
+
+### Example with Pet Store API
+
+The tool has also been tested with the standard Swagger Pet Store OpenAPI definition:
+
+```bash
+# Download the Pet Store spec (if you haven't already)
+# curl -o Examples/petstore.yaml https://raw.githubusercontent.com/swagger-api/swagger-petstore/master/src/main/resources/openapi.yaml
+
+# Convert the Pet Store spec
+swift run openapi-to-symbolgraph Examples/petstore.yaml --output-path petstore.symbolgraph.json
 ```
 
 2. Create a DocC documentation catalog (see `API.docc` as an example)
@@ -47,6 +70,8 @@ xcrun docc convert YourAPI.docc --fallback-display-name YourAPI --fallback-bundl
 
 ## Viewing the Documentation
 
+The `docs/` directory in this repository contains the pre-generated DocC documentation website output for the **Swagger Pet Store API**, which was built using the `petstore.symbolgraph.json` generated by this tool and the `API.docc` catalog.
+
 ### Online Documentation
 
 The latest documentation is automatically deployed to GitHub Pages and can be viewed at:
@@ -55,7 +80,7 @@ The latest documentation is automatically deployed to GitHub Pages and can be vi
 
 ### Local Documentation Server
 
-You can serve the documentation locally using one of these methods:
+You can serve the included Pet Store documentation locally using one of these methods:
 
 #### Using the helper script: