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.

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.

• Convert OpenAPI 3.1.0 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

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

• 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:

# Example using one of the provided files
swift run openapi-to-symbolgraph Examples/api.yaml --output-path api.symbolgraph.json

The tool has also been tested with the standard Swagger Pet Store OpenAPI definition:

# 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)

3. Generate the documentation:

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 Swagger Pet Store API, which was built using the petstore.symbolgraph.json generated by this tool and the API.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 included Pet Store documentation locally using one of these methods:

./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. 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/

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.