I'm a recent Computer Science graduate, and this will be my first open source contribution. I'm very interested in the OpenAPI Integration with DocC project for GSoc 2025. I have a basic proficiency in Swift and a good understanding of HTTP APIs.
I do have a couple of questions as I explore this opportunity:
Eligibility: As a first-time contributor, do I need to be a current student to participate in GSoc 2025, or are recent graduates also welcome?
Project Kickoff: Is there an existing codebase or prototype I should review, or would you recommend starting with a small proof-of-concept to explore the integration of OpenAPI documents with DocC?
Getting Started: Which aspect of the project should I focus on initially—parsing the OpenAPI documents or developing the documentation generation mechanism?
First Steps: Are there any "good first issues" or specific tasks that would help me get acquainted with the codebase and project workflow?
I’m excited to potentially work under the guidance of mentors like @sofiaromorales. Any advice or pointers to get started would be greatly appreciated.
Thank you for your time, and I look forward to contributing to the project.
Hi there,
Thanks for reaching out! I'll let details about the project up to the mentors to reply on but I can help out on the process side of things.
You don't have to be a current student, the program is in general for folks new to OSS, it doesn't have to be active students (people re-skilling or entering software development for the first time are also welcome etc).
The official rules frame it as:
Eligibility.
To participate in the Program, a GSoC Contributor must:
be eighteen (18) years of age or older upon registration for the Program;
for the duration of the Program, be eligible to work in the country in which they reside;
not be an Organization Administrator or Mentor in the Program; and
be a student or a beginner to open source software development.
So that's all fine; and you're doing well already by reaching out like this! More info from project mentors soon. Thank you for your interest!
Project Kickoff: Is there an existing codebase or prototype I should review, or would you recommend starting with a small proof-of-concept to explore the integration of OpenAPI documents with DocC?
Since this project would be about building a library that can ingest an OpenAPI document, and output a DocC Symbol Graph, here are two existing great libraries for working with each format:
A possible first proof of concept could just be to load a sample OpenAPI document and output one simple part of it as DocC Symbol Graph. You could use your favorite HTTP API as an example here.
Getting Started: Which aspect of the project should I focus on initially—parsing the OpenAPI documents or developing the documentation generation mechanism?
Since both formats already have libraries, the value-add of this new project is to translate one into the other. In a similar way that Swift OpenAPI Generator translates OpenAPI documents into Swift code (rather than DocC documentation). Swift OpenAPI Generator also uses OpenAPIKit, by the way.
First Steps: Are there any "good first issues" or specific tasks that would help me get acquainted with the codebase and project workflow?
I think familiarizing yourself with both libraries and trying to use them on simple documents would be a great start here!
Hi @panaze. Thanks for your interest in this project!
Which aspect of the project should I focus on initially—parsing the OpenAPI documents or developing the documentation generation mechanism?
The documentation compiler we'll be using is DocC, so you don’t need to worry about building a documentation generation system from scratch. I suggest you start by getting a general understanding of how the current documentation tool works. You can find more information in the DocC Framework documentation.
As @Honza_Dvorsky pointed out, your project will involve creating a new tool that can convert OpenAPI docs into Symbol Graph Files (SGFs for short).
I’m excited to potentially work under the guidance of mentors like @sofiaromorales. Any advice or pointers to get started would be greatly appreciated.
Can't wait to see what you come up with! Feel free to share your ideas as you go so we can make sure we're all on the same page for the project 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? 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?
