Update project files

Author: ayushshrivastv

API.docc/API.md

@@ -1,18 +1,30 @@
-# ``API``
+# REST API Documentation
 
-A sample API for testing OpenAPI to SymbolGraph conversion.
+A comprehensive REST API example documented with DocC.
 
 ## Overview
 
-This documentation is generated from an OpenAPI specification using the OpenAPI to SymbolGraph conversion tool.
+This documentation is generated from an OpenAPI specification, showcasing how REST APIs can be documented using DocC, the documentation compiler familiar to Swift developers.
 
-## Topics
+## Key Features
 
-### Schemas
+- Auto-generated documentation from OpenAPI schemas
+- Integration with Swift DocC's navigation and search
+- Standard format for HTTP endpoints and request/response schemas
+- Consistent developer experience between Swift API docs and REST API docs
 
-- ``User``
+## Topics
 
 ### Endpoints
 
-- ``getUsers``
-- ``getUserById`` 
+- ``API/listUsers``
+- ``API/getUserById``
+- ``API/createUser``
+
+### Data Models
+
+- ``API/User``
+
+### Getting Started
+
+- <doc:Getting-Started> 

API.docc/Getting-Started.md

@@ -0,0 +1,86 @@
+# Getting Started
+
+Learn how to integrate with our REST API.
+
+## Overview
+
+This guide will help you get started with integrating our REST API into your application. Our API uses standard HTTP methods and JSON for request and response bodies.
+
+## Authentication
+
+All endpoints require authentication. Include your API key in the headers of each request:
+
+```swift
+var request = URLRequest(url: url)
+request.setValue("Bearer YOUR_API_KEY", forHTTPHeaderField: "Authorization")
+```
+
+## Using the API
+
+### Swift Example
+
+Here's a Swift example of how to get a list of users:
+
+```swift
+import Foundation
+
+func fetchUsers(completion: @escaping ([User]?, Error?) -> Void) {
+    let url = URL(string: "https://api.example.com/users")!
+    var request = URLRequest(url: url)
+    request.httpMethod = "GET"
+    request.setValue("Bearer YOUR_API_KEY", forHTTPHeaderField: "Authorization")
+    
+    let task = URLSession.shared.dataTask(with: request) { data, response, error in
+        if let error = error {
+            completion(nil, error)
+            return
+        }
+        
+        guard let data = data else {
+            completion(nil, NSError(domain: "No data", code: 0, userInfo: nil))
+            return
+        }
+        
+        do {
+            let users = try JSONDecoder().decode([User].self, from: data)
+            completion(users, nil)
+        } catch {
+            completion(nil, error)
+        }
+    }
+    
+    task.resume()
+}
+```
+
+### Swift Async/Await Example
+
+Using modern Swift concurrency:
+
+```swift
+import Foundation
+
+func fetchUsers() async throws -> [User] {
+    let url = URL(string: "https://api.example.com/users")!
+    var request = URLRequest(url: url)
+    request.httpMethod = "GET"
+    request.setValue("Bearer YOUR_API_KEY", forHTTPHeaderField: "Authorization")
+    
+    let (data, _) = try await URLSession.shared.data(for: request)
+    return try JSONDecoder().decode([User].self, from: data)
+}
+```
+
+## Error Handling
+
+Our API uses standard HTTP status codes:
+
+- 200 - OK: Request succeeded
+- 400 - Bad Request: Invalid parameters
+- 401 - Unauthorized: Authentication failed
+- 404 - Not Found: Resource not found
+- 500 - Server Error: Something went wrong on our side
+
+## Rate Limits
+
+API requests are limited to 100 requests per minute per API key. 

API.docc/Info.plist

@@ -9,14 +9,10 @@
     <key>CFBundleVersion</key>
     <string>1.0.0</string>
     <key>CFBundleDisplayName</key>
-    <string>API Documentation</string>
-    <key>DefaultCodeListingLanguage</key>
+    <string>REST API Example</string>
+    <key>CDDefaultCodeListingLanguage</key>
     <string>swift</string>
-    <key>DefaultLanguage</key>
-    <string>en-US</string>
-    <key>DocSetPlatformFamily</key>
-    <string>api</string>
-    <key>Title</key>
-    <string>API Documentation</string>
+    <key>CDDefaultModuleKind</key>
+    <string>Library</string>
 </dict>
-</plist> 
+</plist> 

DocsExample/README.md

@@ -0,0 +1,68 @@
+# OpenAPI Integration with DocC Example
+
+This example demonstrates how to document a REST API using DocC, Apple's Documentation Compiler.
+
+## Overview
+
+The example showcases:
+1. Converting OpenAPI specifications to Swift DocC compatible documentation
+2. Generating developer-friendly API documentation
+3. Creating a consistent experience between Swift API docs and REST API docs
+
+## Getting Started
+
+### Prerequisites
+
+- Xcode 15.0 or later
+- Swift 6.0 or later
+
+### Running the Example
+
+1. Clone this repository:
+   ```bash
+   git clone https://github.com/ayushshrivastv/OpenAPI-integration-with-DocC.git
+   cd OpenAPI-integration-with-DocC
+   ```
+
+2. Build the tool:
+   ```bash
+   swift build
+   ```
+
+3. Convert an OpenAPI specification to a SymbolGraph:
+   ```bash
+   swift run openapi-to-symbolgraph api.yaml --output-path api.symbolgraph.json
+   ```
+
+4. Generate DocC documentation:
+   ```bash
+   xcrun docc convert API.docc --fallback-display-name API --fallback-bundle-identifier com.example.API --fallback-bundle-version 1.0.0 --additional-symbol-graph-dir ./ --output-path ./docs
+   ```
+
+5. View the documentation:
+   ```bash
+   python -m http.server 8000 --directory docs
+   ```
+   
+   Then open your browser to http://localhost:8000
+
+## Example Documentation
+
+For a quick preview, you can view the `index.html` file in this directory, which shows a sample of what the generated documentation looks like.
+
+## Structure
+
+- `api.yaml`: Sample OpenAPI specification
+- `API.docc`: DocC documentation catalog
+- `Sources`: Implementation of the OpenAPI to SymbolGraph converter
+- `DocsExample`: Example of the generated documentation
+
+## How It Works
+
+1. The OpenAPI specification is parsed and converted to a SymbolGraph JSON format
+2. DocC uses the SymbolGraph to generate documentation
+3. The documentation is served as a static website
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.