This project aims to create a tool that automatically converts OpenAPI specifications into Swift-DocC compatible documentation. By bridging OpenAPI and Swift-DocC through SymbolGraph files, we'll enable seamless documentation generation for REST APIs within the Swift ecosystem.
The project is still in its very early stage, and I’m actively working on improving it.
Google Summer of Code @Swift project to integrate OpenAPI Integration with Swift-DocC: Automated API Documentation Generation.
Problem Statement
Currently, Swift developers maintaining REST APIs need to manually document their APIs in DocC while separately maintaining OpenAPI specifications. This creates duplicate work and potential inconsistencies between API specifications and documentation.
Command line tool to simplify API documentation for Swift developers. It parses OpenAPI JSON/YAML files using OpenAPIKit Swift Library, transforms schemas and endpoints into DocC ready SymbolGraph files with createSymbolGraph, and outputs “symbolgraph.json.” Users then execute docc convert symbolgraph.json --output-path docs to create HTML docs, enhanced by a static “API.docc/” catalog for custom pages. For GSoC, I’ll extend support for complex schemas like nested objects and arrays, automate DocC conversion, and add live previews, ensuring effortless, consistent API documentation from OpenAPI specs.
swift run openapi-to-symbolgraph <path-to-openapi.json>: Runs your tool to parse and generate “symbolgraph.json.”
docc convert symbolgraph.json --output-path docs: Converts the SymbolGraph into HTML documentation.
Parses OpenAPI specifications (JSON/YAML) Converts API endpoints and schemas into DocC-compatible SymbolGraph files Generates comprehensive API documentation using Swift-DocC
OpenAPI Spec → Parser → Intermediate Representation → SymbolGraph Generator → DocC Integration
- Parses OpenAPI JSON/YAML specifications
- Generates DocC-compatible SymbolGraph files
- Creates documentation structure for API endpoints and schemas
- Xcode 14.0 or later
- Swift 5.7+
- macOS 11.0+
- Clone the repository:
git clone https://github.com/yourusername/OpenAPI-integration-with-DocC.git- Navigate to the project directory:
cd OpenAPI-integration-with-DocC- Build the project:
swift build- (Optional) Run tests:
swift test- Generate the SymbolGraph file:
swift run openapi-to-symbolgraph test/sample-api.json --output- Convert to DocC documentation:
swift run docc convert symbols/symbolgraph.json --output-path ./docs
# Convert a simple API specification
swift run openapi-to-symbolgraph api.json --output ./symbols
Sources/: Contains the main Swift source codetest/: Contains test files and sample OpenAPI specificationsAPI.docc/: Contains DocC documentation catalog
- Swift 5.7+
- macOS 11.0+
This project is licensed under the MIT License - see the LICENSE file for details.