Interested in collab on the OpenAPI integration with DocC project

Development GSoC
1

Hi there, I'm Erik Wasmosy, a Master's computer science student at the University of Rochester (Rochester, NY). I also have 3 years of experience working as both a Backend (80%) and Frontend (20%) engineer. I'm interested in collaborating on this project, and specifically I want to be more involved in the Swift community. It's something I've wanted since my first year in my developer journey, where my first path was learning iOS development since I enjoy using iOS apps a lot and always loved how good people make these apps look.

I built a tic-tac-toe game with my cousins' and friends' faces as characters and also included DLC as a fun feature (my aunt's face was the special and expensive one). Then I prototyped an app guide for Valorant and CSgo players on how to create special movements and throw objects correctly across the map (something I want to continue building after 3 years). But my work experience didn't let me go deep on Swift development, and I had to use and learn other programming languages, frameworks, etc. So I want to take this opportunity to improve my knowledge in Swift, contribute to making it better, and be part of this community.

Some experience that I have that is relevant for this project:

  • As I mentioned, I have basic experience doing some iOS app coding with Swift, only personal projects.
  • I use a lot of OpenAPI documentation when building microservices endpoints in my work, specifically with the Python FastAPI library.
  • I have experience working collaboratively, and documenting my APIs was really enjoyable. I was strict about doing it the right way for other developers using my endpoints.
  • In my undergraduate university, we had a GSoC-like experience but we called it UC Autumn of Code (AoC). This is my third year being a mentor there, where I teach students (mentees) how to build separate microservices, work collaboratively, and how to deal with documentation so everyone understands each other's microservices to connect them well together. But this time I will glad to be a mentee for a GSoC and specially in swift.

@sofiaromorales @Honza_Dvorsky I will be glad of any guidance on how to collaborate in this project.

Thanks,
Erik

2

Hi @erwaen

Thanks for your interest in this project!

@sofiaromorales @Honza_Dvorsky I will be glad of any guidance on how to collaborate in this project.

There are multiple ways you can get started. I recommend first doing some research on DocC and OpenAPI to get a better understanding of how they work. Both DocC and OpenAPIKit also have good first issues that you can try to solve, which will help you familiarize yourself with the tools involved in this project.

It might also be useful to prototype something small, like a proof of concept. For example, you could create a tool that loads an OpenAPI document and generates a simple DocC SymbolGraph.

These things will help you come up with questions for discussions and discover important design decisions for the tool that you to include in your proposal :)

1 Like
3

Thanks for the suggestions, Sofia! I'm going to research DocC and OpenAPI now, and then take a look at the first issues. I just finished a midterm exam, so I'll focus on this now. I hope by the end of the weekend I'll have gained enough knowledge on these topics to continue with the proposal. I'll write here if I have other questions. Thanks!

1 Like
4

I did some research about DocC and SymbolGraph, if I understood correctly, when the project is built, it generates a *.symbols.json file that I think is supposed to contain all the relationships of the modules. Then, to create the DocC we have to run the DocC command which uses this generated symbols file to build the nice documentation. Is that correct? Also, to understand better, I always like to do this process step by step. Do you have any ideas where I can find this symbols file after running, for example swift build in the SlothCreator example project so I can take a look at its content and how it looks like. (I think in xcode Product -> Build documentation performs all those steps as a in integrated process)

@sofiaromorales @Honza_Dvorsky @sebeaumont

5

Yes, exactly - that's the general flow that's happening. If you just build a swift package, it doesn't generally expose the symbols - it requires some additional CLI options if you want to get them explicitly, and that whole process of requesting them during a build is generally hidden behind tooling such the swift-docc-plugin.

Borrowing from a script I worked on for the Euclid project some time ago (prior to the plugin existing), what this looks like is:

$(xcrun --find swift) build --target Euclid \
-Xswiftc -emit-symbol-graph \
-Xswiftc -emit-symbol-graph-dir -Xswiftc .build/symbol-graphs

This specifically puts the generated symbols into the .build/symbol-graphs directory, and earlier in that little script I created the directory to hold them prior to their generation.

And yes, you're quite correct that when you do this sort of thing within Xcode, that's all encapsulated and driven by Xcode's build system.

A possible pain point here - If the example project that you're exploring is constrained to iOS while you're working on macOS, using the CLI options for running swift build directly only build for the local host (that is, macOS). There is a workaround to use xcodebuild docbuild to generate documentation, but I don't know if we can intercept the symbolgraph files in that case. But more generally, many packages support building on macOS (or Linux) if your primary goal is to explore what a symbolgraph looks like.

2 Likes
6

Hi Joseph, thank you for your help! Yes, with that command, I was able to generate the symbol graph. I'll take a look at what it includes, but the file is so huge that my Neovim just crashed :joy:. VS Code handles it well.

And thanks for the iOS insight as well, that makes sense why the xcodebuild command didn't work with this project

1 Like