Merge branch 'main' into feature/organize-examples

Signed-off-by: Ayush Srivastava <ayush.srivastav@icloud.com>

Author: ayushshrivastv

README.md

@@ -1,34 +1,37 @@
 # OpenAPI Integration with DocC
 
-This project provides tools and examples for integrating OpenAPI specifications with Apple's DocC documentation system. It allows developers to create beautiful, interactive documentation for REST APIs that matches the style and quality of Swift API documentation.
+The project aims to bridge the gap between OpenAPI specifications and Swift's DocC documentation framework by developing a tool that automates the generation of DocC documentation from OpenAPI files.
 
 ## Overview
 
 OpenAPI is the industry standard for documenting HTTP services, but Swift developers are already familiar with DocC for their Swift and Objective-C API documentation. This project bridges that gap by converting OpenAPI specifications into a format that DocC can understand and render.
 
-## Key Features
-
-- Convert OpenAPI 3.x specifications to DocC-compatible format
-- Generate beautiful API documentation
-- Provide a consistent documentation experience for Swift developers
-- Support for documenting endpoints, schemas, parameters, and more
+![2048](https://github.com/user-attachments/assets/f9a751be-9d2f-43f0-8346-04af7edaea57)
 
 ## Project Structure
 
 The project is organized into several modules:
 
-- `Sources/OpenAPI` - Core functionality for parsing OpenAPI specifications.
-- `Sources/OpenAPItoSymbolGraph` - Main implementation for converting OpenAPI models to SymbolGraph.
-- `Sources/Integration` - Integration points, potentially including the CLI tool.
-- `Sources/openapi-to-symbolgraph` - The command-line executable target.
-- `Tests/OpenAPItoSymbolGraphTests` - Unit and integration tests.
+- `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
+
+## Key Features
+
+- Convert OpenAPI 3.1.0 specifications to DocC compatible format
+- Generate API documentation
+- Provide a consistent documentation experience for Swift developers
+- Support for documenting endpoints, schemas, parameters, and more
 
 ## Getting Started
 
 ### Prerequisites
 
-- Xcode 15.0 or later (requires Swift 5.9+ for DocC support)
-- Swift command-line tools configured (`xcrun`)
+- Xcode 15.0 or later
+- Swift 6.0 or later
+- Python 3 (for local documentation serving)
 
 ### Installation
 
@@ -38,107 +41,82 @@ cd OpenAPI-integration-with-DocC
 swift build
 ```
 
-### Usage Steps
-
-1.  **Obtain your OpenAPI Specification:** Ensure you have your API specification in a `.yaml`, `.yml`, or `.json` file (OpenAPI v3.x format).
-2.  **Generate SymbolGraph:** Run the command-line tool, providing the path to your OpenAPI file.
-
-    ```bash
-    swift run openapi-to-symbolgraph <path_to_your_openapi_spec> --output-path <desired_symbolgraph_name>.symbolgraph.json
-    ```
-
-3.  **Prepare SymbolGraph Directory:** Move the generated `.symbolgraph.json` file into a dedicated directory (e.g., `symbolgraphs`).
-
-    ```bash
-    mkdir symbolgraphs
-    mv <desired_symbolgraph_name>.symbolgraph.json symbolgraphs/
-    ```
-
-4.  **Create a DocC Catalog:** Create a basic documentation catalog directory (e.g., `MyAPI.docc`). This needs at least one markdown file to serve as the root landing page.
-
-    ```bash
-    mkdir MyAPI.docc
-    # Create a root file, e.g., MyAPI.docc/MyAPI.md
-    echo "# MyAPI\\n\\nAPI Documentation landing page." > MyAPI.docc/MyAPI.md
-    ```
-
-5.  **Generate DocC Archive:** Use `xcrun docc convert` to combine your catalog and symbol graph into a `.doccarchive`.
+### Usage
 
-    ```bash
-    xcrun docc convert MyAPI.docc --additional-symbol-graph-dir symbolgraphs --output-path MyAPI.doccarchive
-    ```
+1. Convert your OpenAPI specification to a SymbolGraph:
 
-6.  **View Documentation:** Open the generated `MyAPI.doccarchive` file in Xcode, or host it on a web server.
-
-### Example: Swift Package Registry API
-
-This example demonstrates generating documentation for the official Swift Package Registry API.
+```bash
+swift run openapi-to-symbolgraph Examples/api.yaml --output-path api.symbolgraph.json
+```
 
-1.  **Download the Spec:**
+### Example with Pet Store API
 
-    ```bash
-    # Create a directory for test resources if it doesn't exist
-    mkdir -p Tests/OpenAPItoSymbolGraphTests/Resources
+The tool has also been tested with the standard Swagger Pet Store OpenAPI definition:
 
-    # Download the registry spec
-    curl -o Tests/OpenAPItoSymbolGraphTests/Resources/registry.openapi.yaml https://raw.githubusercontent.com/swiftlang/swift-package-manager/main/Documentation/PackageRegistry/registry.openapi.yaml
-    ```
+```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
 
-2.  **Generate SymbolGraph:**
+# Convert the Pet Store spec
 
-    ```bash
-    swift run openapi-to-symbolgraph Tests/OpenAPItoSymbolGraphTests/Resources/registry.openapi.yaml --output-path registry.symbolgraph.json
-    ```
+swift run openapi-to-symbolgraph Examples/petstore.yaml --output-path petstore.symbolgraph.json
+```
 
-3.  **Prepare Directory:**
+2. Create a DocC documentation catalog (see `API.docc` as an example)
 
-    ```bash
-    mkdir -p symbolgraphs # Ensure directory exists
-    mv registry.symbolgraph.json symbolgraphs/
-    ```
+3. Generate the documentation:
 
-4.  **Create Catalog:** (We created `RegistryAPI.docc` earlier)
+```bash
+xcrun docc convert YourAPI.docc --fallback-display-name YourAPI --fallback-bundle-identifier com.example.YourAPI --fallback-bundle-version 1.0.0 --additional-symbol-graph-dir ./ --output-path ./docs
+```
 
-    ```bash
-    # Ensure the catalog exists and has a root file
-    mkdir -p RegistryAPI.docc
-    echo "# RegistryAPI\\n\\nSwift Package Registry API documentation." > RegistryAPI.docc/RegistryAPI.md
-    ```
+## Viewing the Documentation
 
-5.  **Generate Archive:**
+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.
 
-    ```bash
-    xcrun docc convert RegistryAPI.docc --additional-symbol-graph-dir symbolgraphs --output-path RegistryAPI.doccarchive
-    ```
+### Documentation
 
-    This creates `RegistryAPI.doccarchive`, which contains the generated documentation for the Swift Package Registry API.
+The latest documentation is automatically deployed to GitHub Pages and can be viewed at:
 
-## Viewing the Documentation
+[https://ayushshrivastv.github.io/OpenAPI-integration-with-DocC/](https://ayushshrivastv.github.io/OpenAPI-integration-with-DocC/)
 
-You can view generated `.doccarchive` files in Xcode or host them online.
+### Local Documentation Server
 
-### Example Pet Store Documentation (Pre-built)
+You can serve the documentation locally using one of these methods:
 
-The `docs/` directory in this repository contains pre-generated DocC website output for the **Swagger Pet Store API**. This was built using `Examples/petstore.yaml` and an example `API.docc` catalog.
+#### Using the helper script:
 
-**View Online:** [https://ayushshrivastv.github.io/OpenAPI-integration-with-DocC/](https://ayushshrivastv.github.io/OpenAPI-integration-with-DocC/)
+```bash
+./serve-docs.sh
+```
 
-**Serve Locally:**
+#### Using Python 3 directly:
 
 ```bash
-# Serve the pre-built Pet Store docs
 python3 -m http.server 8000 --directory docs
 ```
 
-Then open http://localhost:8000 in your browser.
+Then open your browser to http://localhost:8000
 
-## Testing
+## Example
 
-The tool includes a comprehensive test suite (`swift test`) covering parsing, conversion, and command-line arguments, using examples like the Pet Store API and the Swift Package Registry API.
+Check out the `DocsExample` directory for a working example of a REST API documented with DocC. It showcases how endpoints, schemas, and examples appear in the DocC format.
+
+## How It Works
+
+1. The OpenAPI specification is parsed using `OpenAPIKit`
+2. The specification is converted to a SymbolGraph, which is the format DocC uses for documentation
+3. DocC processes the SymbolGraph and generates the documentation
+4. The documentation can be served as a static website or deployed to GitHub Pages
 
 ## GitHub Pages Deployment
 
-This repository automatically deploys the pre-built Pet Store documentation from the `docs` directory to GitHub Pages via the `.github/workflows/pages.yml` workflow.
+This repository is configured to automatically deploy documentation to GitHub Pages whenever changes are pushed to the main branch. The deployment process:
+
+1. Uses the GitHub Actions workflow defined in `.github/workflows/pages.yml`
+2. Takes the contents of the `docs` directory
+3. Deploys them to GitHub Pages
+4. Makes the documentation available at the URL: [https://ayushshrivastv.github.io/OpenAPI-integration-with-DocC/](https://ayushshrivastv.github.io/OpenAPI-integration-with-DocC/)
 
 ## Contributing