REST API Documentation with DocC
This project showcases how OpenAPI specifications can be transformed into beautiful, interactive documentation using Swift's Documentation Compiler (DocC).
The docs folder contains the HTML files generated by DocC using the command:
docc convert symbolgraph.json --output-path docs
This conversion process maps OpenAPI components to SymbolKit symbol kinds:
- Module: "User API v1.0"
- Structs: User and other data models
- Functions: API endpoints like getUsers
Example Endpoints
The documentation includes complete details about request parameters, response models, and examples for endpoints such as:
GET /users- Retrieve all usersGET /users/{id}- Get a specific user by IDPOST /users- Create a new userPUT /users/{id}- Update an existing user
Exploring the Documentation
The DocC documentation provides several ways to explore the API:
- Navigation: Browse through API endpoints organized by resource type
- Search: Find specific endpoints, parameters, or data models
- Interactive Examples: See request/response examples for each endpoint
- Schema Definitions: View detailed information about data structures
Technical Implementation
The conversion process from OpenAPI to DocC involves:
- Parsing the OpenAPI specification
- Generating SymbolGraph JSON
- Converting the SymbolGraph to DocC documentation
- Rendering the documentation as HTML
Benefits of DocC Documentation
Using DocC for API documentation offers several advantages:
- Consistent styling with the Apple developer documentation ecosystem
- Excellent navigation and search capabilities
- Support for dark mode and responsive design
- Integration with Xcode and Swift development workflows
- Automatically generated syntax highlighting and code formatting