@sofiaromorales, Having attempted to generate basic documentation for conversion documentation, I am seeking guidance on the next steps to take. I have recently updated the GitHub repository.
docc convert symbolgraph.json --output-path docs
I’ve completed this step and now I’m wondering if I should try integrating it into the OpenAPI Generator. I’ve seen the basic structure in the documentation, and I need to integrate it with Swift-DocC.
Could you please review my updated proposal so that I can identify and address any potential issues?
Apologies if I made any errors. Actually, I'm 20 years old, and this is the first time I'm applying for any open source program or even an internship, so I’m getting used to what to do or not. I wanted to ensure that I can continue working on the project as proof of concept. So far, I have successfully saved the symbolgraph.json file and executed the docC convert command. Here’s the code on GitHub, So that if I'm doing anything wrong, I can address the issue with feedback.
Also I have overlooked bold text as I have written it down in my reminders app to ask for a proposal review. I have simply copied and pasted the text from there.
Will we be using AsyncHTTPClient Transport for Swift OpenAPI Generator to integrate the tool within the openapi generator? Also, since I’m hosting a documentation on an HTTP server and docC already has an implementation, do I need to write separate code for that, or can I use that implementation, as you mentioned earlier?
I was browsing through the documentation and Introduction for OpenAPI Generator, as it was mentioned as a stretch goal. I noticed that OpenAPI Generator already has existing transport implementations. Which is using HTTP LIBRARY INTERFACE in the protocols ClientTransport and ServerTransport.
I’m looking into how Open API operations map to Swift functions based on the transport. This will aid my tool in generating matching SymbolGraph symbols.
SymbolGraph might not directly show if a function is async, but we can add SymbolKit’s isAsync flag for HTTP operations.
AsyncHTTPClient Transport can handles many HTTP requests at once without waiting, using asynchronous, nonblocking operations. as it ensures the generated code and DocC documentation reflect these fast, async API calls for Swift developers.
In SymbolGraph, the signature field can include the async keyword. This way, DocC can handle async functions.
But I'm aware that asynchronous HTTP is a runtime concern and will have no major effect on documentation.
I'm just trying to understand how things are set up between OpenAPI and docC so it will help me better understand the workflow of code, if we go towards server implementation.
Currently, I have two dependencies that will map OpenAPI with Symbolgraph.
I’ve made some revisions to the proposal and added more explanations to make it clearer. Would you like me to explain the technical details in more detail? I’ve reviewed the documentation and even tried to implement some of the project components. Please share any other suggestions you have for improving the proposal, I’d love to hear them!
Could you provide more details on how the mapping will work between the OpenAPI structure (the information, paths, and operations) and the SymbolKit symbol kinds? Are you planning to create new symbol types, or do the existing ones in SymbolKit already cover everything you need?
Also, do you have a working example of a REST API documented with DocC that people can check out?
Just a friendly reminder, the proposal needs to be submitted via the GSoC website, and the deadline is April 8 at 18:00 UTC.
For the mapping process, the API root (info) maps to swift.module, schemas to swift.struct, properties to swift.property, operations (GET /users) to swift.func, parameters to swift.var, and responses to swift.enum. Currently, I believe SymbolKit’s existing kinds cover everything, so we won’t need any new types.
I’m curious to know if this approach is what you had in mind or if there’s anything I might be missing. I just want to make sure I’m on the right track!
Also, do you think I should expand on the mapping details further in the proposal before I submit the final draft by tomorrow.
I’ve submitted my final proposal for the OpenAPI Integration with DocC Project on the Google Summer of Code Page.
While I could provide additional details, I think it would get too complicated. Since the proposal already has sixteen pages, instead I’ve added OpenAPI Integration with the DocC GitHub repository code link. This code has all my current progress, so it will be easy to run and test the initial development phase.
I need help with an issue I’ve been encountering when attempting to create a pull request for the Swift DocC repository. Despite disabling all reformatted settings, I’m noticing an excessive number of whitespaces being added to the entire file during the staging process. This issue is specific to this repository and doesn’t affect other repositories.
I’ve raised two PRs in the OpenAPIKit repository, and there wasn’t any such issue. I’m also not encountering any problems with current working project OpenAPI Integration with DocC repository.
I'm excited to share my current progress on integrating OpenAPI specifications with DocC documentation. This project aims to create a seamless experience for Swift developers by converting OpenAPI documents into DocC compatible documentation, making API references consistent with the rest of the Swift ecosystem.
Current Progress
I've developed a working conversion tool that transforms OpenAPI documents into SymbolKit symbol graphs, which can then be processed by DocC to generate documentation.
Mapping OpenAPI to SymbolKit
Mapping OpenAPI to SymbolKit starts with defining a central container. A top level module symbol, that acts as the root of the API structure. Everything else is organised under this container to form a clear, modular layout that reflects the overall design of the API.
Each schema or model in the OpenAPI document is turned into a corresponding symbol in SymbolKit. The properties within these schemas are mapped as variables, with their types, constraints, and descriptions all preserved. This helps ensure the documentation remains accurate, readable, and fully aligned with the API's intended behavior.
API operations, like GET and POST are handled like functions. Each one includes its input parameters such as path, query, and body data and clearly defines what it returns by linking to the right model. This gives a structured, predictable view of how the API behaves.
To tie everything together, we define relationships between these symbols using SymbolKit’s built in types like .memberOf and .returns. These links show how different pieces are related, for example, which functions belong to which modules, and which models are returned from which endpoints. The result is a clean, well organised symbol graph that makes the entire API easy to explore and document using DocC.
Right now, most of this logic lives in the SymbolMapper struct located in Sources/SymbolMapping.swift, which implements the core logic for mapping OpenAPI elements to SymbolKit symbols.
OpenAPISymbolKind Enum
Defines internal symbol types (.namespace , .endpoint , .schema ) for mapping OpenAPI content to SymbolKit constructs.
enum OpenAPISymbolKind {
case namespace
case endpoint
case schema
case property
}
mapSchemaType Function
This function takes an OpenAPIKit.JSONSchema and recursively maps OpenAPI data types to their Swift equivalents, extracting constraints along the way.
static func mapSchemaType(_ schema: OpenAPIKit.JSONSchema) -> String {
switch schema.coreContext.type {
case .string:
return "String"
case .number:
return "Double"
case .integer:
return "Int"
case .boolean:
return "Bool"
case .array:
if let items = schema.items {
return "[\(mapSchemaType(items))]"
}
return "[Any]"
case .object:
default:
return "Any"
}
}
createSymbol Function
Creates a symbol based on the given kind, name, identifier, and path. Converts OpenAPISymbolKind into SymbolKit types like .schema → swift.struct .
I've added a code base link for the complete mapping process as this post just summarizes the mapping process. You can refer to the code base if I missed something here.
So far, I’ve only used existing SymbolKit symbol kinds - I haven't needed to create new ones.
Swift Build Command Output
$ swift build
Building for debugging...
[7/7] Linking openapi-to-symbolgraph
Build complete! (1.37s)
After building, I ran a sample API file
$ swift run openapi-to-symbolgraph api.yaml
Building for debugging...
[7/7] Applying openapi-to-symbolgraph
Build of product 'openapi-to-symbolgraph' complete! (1.37s)
Parsing YAML...
Processing paths...
Processing schemas...
Symbol graph generated at /Users/ayushsrivastava/OpenAPI-integration-with-DocC/openapi.symbolgraph.json
This confirms that the tool is working as expected and the generated symbolgraph.json is ready for DocC conversion.
This .json symbol graph is then processed by DocC to produce user friendly documentation.
This tool reads OpenAPI documents in YAML or JSON formats using the OpenAPIKit library. It takes the entire API structure, including operations, schemas, and relationships, and maps everything into a symbol graph.
This process keeps all the detailed documentation, like descriptions, examples, and status information, intact. After building the symbol graph, the tool outputs a standard JSON file that DocC can process to generate the final, user friendly documentation.
The conversion process involves parsing the OpenAPI document, creating and mapping a symbol graph, linking together all the elements, and then using DocC to produce the final documentation.
Right now, the tool can successfully parse OpenAPI documents.
Read the OpenAPI document
Creates valid symbol graph files
Handles schemas, operations, and their relationships
Has some symbol resolution issues when generating DocC documentation. In coming days, I will try to solve this issue while creating a REST API example.
I'm working on creating a publicly accessible example of a REST API documented with DocC. Currently, test APIs generate valid symbol graphs, but the final DocC integration needs some enhancement before sharing a public demo. But I'll have a well crafted example for a REST API that is documented using DocC before the Google Summer of Code period begins.
swift run openapi-to-symbolgraph <path-to-openapi.json>: Runs the tool to parse the OpenAPI document and generate `symbolgraph.json`.
docc convert symbolgraph.json --output-path docs: Converts the generated SymbolGraph into HTML documentation
Once we run the command to convert the symbolgraph.json into HTML documentation, the resulting files will be in the docs folder. Then we can host the static docs folder generated by DocC on an HTML server.
While working on the issue in the repository OpenAPIKit, where I was attempting to add a validation that checks all operationIds in Link objects are valid, during the debugging process I got a better approach from my initial thinking of how we can use the mapping process, and I've started working on that approach as well.
Additionally, these two pull requests have been successfully "Merged" into the OpenAPIKit Code base.
Thank you, @mattpolzin, for taking your time and assisting me!
I’ve spent the last few weeks working on this project and reading the surrounding documentation and code, and this post serves as my current progress after a month!
Since you all have more experience working with OpenAPIKit and DocC Codebases. If you guys can look into the actual code, that would be really helpful to clarify things.
In the coming weeks, I’ll first attempt to generate a REST API documented using DocC. I’ll also improve the code line up, as there are some version related warnings that are need to be addressed. Additionally, I’ll further enhance the path, schema, and query functions for mapping process and api operations.
I'd love to hear your feedback @sofiaromorales@ktoso@Honza_Dvorsky on the mapping approach and any suggestions for improving the integration between OpenAPI and DocC from the Swift community that will be highly helpful!
