Hello everyone,
I am pleased to present my proposal for the Google Summer of Code @Swift project titled “OpenAPI integration with DocC.” I would appreciate your feedback on this proposal.
Proposal @sofiaromorales @Honza_Dvorsky @beaumont
I will continue to refine it based on the feedback I receive.
thank you...
Is this a correct base level approach / understanding of the project’s core? Am I overlooking something here? 
Hi @sofiaromorales, So that means I've to use OpenAPIKit to parse OpenAPI docs and map them to SymbolKit SymbolGraphs, feeding into DocC for rendering. Thanks for your input!
Thank you for the feedback. I’ve further improved the plan.
I’m using OpenAPIKit to create a bridge between SymbolKit and DocC. Is this the best way to go about it?
thankyou!
Hi @ayush.srivastav,
I'm the org admin for the Swift project's participation in GSoC this year.
I wanted to provide some high-level process feedback about the proposal. It seems very high level and almost like something that might have been generated using an LLM tool. GSoC's purpose is to learn and grow while contributing to open source, so more than pristine generic plans, it's quite a lot about interacting and figuring out the details/plans/implementations with your mentors.
Would you mind reworking it using your own words and provide more details and dig into the exact pieces of the project you'd like to work on? For example, what is the result of the project, is it a tool, addition to docc? When mentioning "testing" could you clarify if there's some end goal you'd like to be able to achieve to be able to call this project "done."?
Please continue to work with @sofiaromorales and @Honza_Dvorsky if you have more questions and need support.
Thank you for your time and I hope we can help you come up with a nice proposal that will then be submitted 
To improve your understanding of the systems involved, you could do this before writing the proposal. This will help you uncover some unknowns about the tool and allow you to come back with questions that the mentors can guide you through. A proof of concept would be helpful to understand the mapping between the elements of an OpenAPI doc and a SymbolGraph (SG).
The proof of concept will help you answer questions like: Does the OpenAPI doc contain all the information necessary to generate an SG? If not, what information is missing, and how can I provide it? How strict is SymbolKit with the types of symbols it declares? Is there any work needed on SymbolKit to make this work? At the UI level, how would a page documenting an endpoint look?
These are some of the questions that could arise and having them answered before starting the project will set us up for success.
Thank you for the response!
at present, I have included the research part in the proposal so that I can draft it. I will improve it further in the coming days as I become clearer about my approach and any doubts I may have. This will allow me to add or remove things as needed. Sorry for any inconvenience...
I did understood the project that we are working translating a simple OpenAPI docs to SymbolGraphFiles and for that we can use OpenAPIKit project and DocC module to input data to produce documentation so that we can enable DoC to render Documentation with the help of SymbolKit to map the OpenAPI data....
actually, I'm new to open source discussions, and it was easy for me to look for code and solve the issue on GitHub, but I did get it. It is important to communicate, and I will be working on it. Thank you for the feedback. @ktoso
thank you so much @sofiaromorales for the detailed explanation of the project. Now, as the project is clear to me, I can start working on how I can approach the project. And if I get an issue, I will let you know...
It is indeed very helpful in understanding how the discussions that take place in open source projects help me as I was figuring out how I should ask questions.
thanks for sharing this..
I'm working on an issue in the DocC repository and I have one question
I have added diagnostic for multiple root pages warning, root page count validation, test coverage to verify warning message and details as it was requested in the issue section
but the problem is I've not touched any other files or previous code of this file then why it is showing +6482 -4195 lines changed.. I've just added this function to validate root page and the test case..
Is I'm doing anything wrong here, what I expect should be changes I did, added validate root page and the test case so it should show plus (+ line added in that particular file ). So why it showing so many lines deleted or added?
After adding this feature, I tested it locally. It built successfully without any errors, and on the GitHub page, it asked me Reviewer required : At least 1 approving review is required by reviewers with write access." just wanted to confirm do I need to do anything for this from my side?
An example similar to this one has not even been touched by me, yet it is displaying an edited version
It appears you have reformatted and reindented the code.
actually I didn't that's why I'm confuse. I just added the code at the designated place and then ran the test. Plus, I have re-forked the repo and tried it again. I just copied and pasted from the previous repo and only the addition part which I've written without touching anything else in the codebase. And it again happened the same. Does using Copilot affect this while debugging?
@jack I’ve figured out why it happened. My pull request was full of changes ‘cause VS Code went and reformatted DocumentationContext.swift and DocumentationContextTests.swift when I hit save. I only wanted to add a function and a test, but it proper mucked up loads of lines. I’ve changed the editor.formatOnSave setting now..
thankyou..
I’ve tried to built OpenAPI data to SymbolGraph conversion tool, and I’m able to successfully generate SymbolGraph JSON files from OpenAPI!
however, I'm encountering an issue when trying to use DocC to generate documentation from these files, while running either docc convert or docc preview commands, I get this error
SwiftDocC/DocumentationContext.swift:1153: Fatal error: Symbol with identifier 'f:get_users' has no reference. A symbol will always have at least one reference.
when converting OpenAPI endpoints and schemas to SymbolGraph symbols, what specific fields and structure does DocC require? currently conversion generates basic symbol information but DocC reports missing references. Could you help me identify the required fields for proper symbol recognition?
Hi Ayush
This is an error that happens when the symbol graph contains a relationship where the source symbol doesn’t exist in the symbol graph.
For example, let's say we have two symbols, Color and Yellow, there is a relationship between them defined as follows:
{
"kind" : "memberOf",
"source" : "yellow",
"target" : "color",
"targetFallback" : null
}
With the respective symbol definitions:
{
"kind": {
"identifier": "swift.type.property",
"displayName": "Type Property"
},
"identifier": {
"precise": "color",
"interfaceLanguage": "swift"
},
"pathComponents": [
"light",
],
"names": {
"title": "color"
},
"navigator" : [...],
"declarationFragments": [...],
"accessLevel": "public",
}
{
"kind": {
"identifier": "swift.type.property",
"displayName": "Type Property"
},
"identifier": {
"precise": "yellow",
"interfaceLanguage": "swift"
},
"pathComponents": [
"light (foo)",
"color",
],
"names": {
"title": "yellow"
},
"declarationFragments": [...],
"accessLevel": "public",
}
Notice how the path component of the child symbol contains a symbol that does not exist. This is caused by an error in the symbol graph generation process.
when converting OpenAPI endpoints and schemas to SymbolGraph symbols, what specific fields and structure does DocC require?
The SymbolGraph follows the definition provided by SymbolKit. Your tool can use this as a dependency to generate valid symbols and valid symbol graph structures. By looking at the source code, we can infer the required attributes for a symbol. (swift-docc-symbolkit/Sources/SymbolKit/SymbolGraph/Symbol/Symbol.swift at main · swiftlang/swift-docc-symbolkit · GitHub).
You also might find interesting to see that there is already some support for http symbols in the codebase (swift-docc-symbolkit/Sources/SymbolKit/SymbolGraph/Symbol/HTTP/HTTP.swift at main · swiftlang/swift-docc-symbolkit · GitHub), just highlighting this as it might be useful for your tool.
Thank you so much, @sofiaromorales, for the detailed explanation! Since SymbolKit already supports HTTP, I’ll explore how to make use of it. I’ve shared the codebase on GitHub. It currently contains only the basic project structure, but I’ll be making improvements. I’d appreciate any suggestions you may have for me to follow from here!