I am Eshan a 4th year CS student . I have been a past GSoC 2023 contributor with VideoLAN where I worked on VLCMediaLibrary Integration on their tvOS app which involved mix of writing Swift and Objective C interoperable code.
I particularly interested in this project, where a tool has to created to bridge the gap between OpenApi docs and DoC C .
To get started I would love to know any specific guidance from the mentors on the parts of the DocC codebases I should explore first so that I maybe try to build an implementation which I can propose ? Do I need to propose a demo around that to check I am thinking in the right direction ?
Like do we need to build a separate tool , or maybe we can implement parsers inside the main project ?
I also recommend checking the DocC codebase to get an idea on how the DocC compiler works and how it uses the input data to produce documentation.
I should explore first so that I maybe try to build an implementation which I can propose ? Do I need to propose a demo around that to check I am thinking in the right direction ?
You don’t need to build a fully functional demo, but I recommend you to either create a small proof of concept or spend some time getting familiar with these technologies, one way of doing this it's by looking at good first issues in any of the repos.
If you'd like to give developing a working proof of concept a try, as @Honza_Dvorsky mentioned here, a great place to start could be translating a simple OpenAPI document into a Symbol Graph.
Like do we need to build a separate tool , or maybe we can implement parsers inside the main project ?
We're thinking of this as a standalone tool that can later be used as a dependency in projects like the Swift OpenAPI Generator or in VSCode plugins. It could make use of the technologies listed above to help translate between OpenAPI docs to SymbolGraphFiles (SGFs).
@Honza_Dvorsky, @beaumont, and I are really looking forward to seeing what you come up with! Feel free to share your ideas as you go, we’re here to give feedback and help you refine your proposal :)
@sofiaromorales@Honza_Dvorsky As per exploration , (I tried experimenting with a sample file) What I am thinking the tool will first parse the OpenAPI document (YAML/JSON) by first iterating through all the OpenAPI components with the help of OpenAPIKit .
This information will be used by SymbolGraphKit to generate the references and symbol components, to generate SGFs which will then be feeded to / used by DoC to generate documentation . The main value addition according to me is the swift logic written should be dynamically adaptable to any kind of open api file , logic of that will be handled by this tool. (Which is the main value addition of this GSoC Project).
Regarding the proposal (Once I start working on it), I can share it here or email works fine?
Right, components would be the first part to generate as SGFs, and operations would be the second one. Yes it should be able to handle any valid OpenAPI document.
For inspiration, you can check out existing OpenAPI documentation renderers, like Redocly and swagger-ui, and think about what the right structure would be for viewing these in docc.
Is there any updated documentation for the Swift Package Registry API that covers integrating support for explicit JSON schema dialect specifications within package metadata schema definitions? Specifically, I’m interested in learning more about this feature and how it could be implemented in a declarative Swift codebase, possibly using OpenAPIKit’s JSONSchema types. I’ve raised a PR (Add support for specifying JSON schema dialects (fixes #202) #401) to address this issue, and I believe we can further improve it. Could you provide some guidance on implementation and potential enhancements?
Regarding the proposal (Once I start working on it), I can share it here or email works fine?
The Swift forums allow sending direct private messages to other contributors. So feel free to share the proposal via DMs if you prefer to receive private feedback before submitting it.
I’ve thoroughly reviewed the documentation and codebase. I’ve submitted two pull requests to address the issues mentioned:
It’d be great if we could get these merged before the submission deadline so you can include them in the proposal. But if that’s not possible, you can still mention them as blockers for part of the implementation in your proposal.
Is there any updated documentation for the Swift Package Registry API that covers integrating support for explicit JSON schema dialect specifications within package metadata schema definitions?
While solving the JSON schema issue (#401), I saw room for further improvement. I checked the docs but might’ve missed something. I was simply curious about learning more about the Swift package registry and I couldn't find the docs for it—thanks for sharing!
I’m drafting a Swift proposal and will share it with you within the next one to two days. Thank you.
