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.

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.

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

• 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

• Xcode 15.0 or later
• Swift 6.0 or later
• Python 3 (for local documentation serving)

git clone https://github.com/ayushshrivastv/OpenAPI-integration-with-DocC.git
cd OpenAPI-integration-with-DocC
swift build

1. Convert your OpenAPI specification to a SymbolGraph:

swift run openapi-to-symbolgraph Examples/api.yaml --output-path api.symbolgraph.json

2. Generate the documentation using our helper script:

./scripts/build-docs.sh

Or manually with DocC:

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

The docs/ directory in this repository contains the pre-generated DocC documentation website output for the Swift Package Registry API, which was built using the registry.symbolgraph.json generated by this tool and the RegistryAPI.docc catalog.

The latest documentation is automatically deployed to GitHub Pages and can be viewed at:

https://ayushshrivastv.github.io/OpenAPI-Integration-with-DocC/

You can serve the documentation locally using one of these methods:

./scripts/local-preview.sh

This script serves the documentation directory and opens it in your browser. You will be automatically redirected to the API documentation.

./scripts/serve-docs.sh

python3 -m http.server 8000 --directory docs

Then open your browser to http://localhost:8000

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.

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

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. Builds the documentation from the OpenAPI specification
3. Takes the contents of the docs directory
4. Deploys them to GitHub Pages
5. Makes the documentation available at the URL: https://ayushshrivastv.github.io/OpenAPI-Integration-with-DocC/

Contributions are welcome! Please feel free to submit a Pull Request.

This project is licensed under the MIT License - see the LICENSE file for details.