My Experience about GSoC 2019 with Developers Italia
What is “Google Summer of Code”
Google Summer of Code, also known as GSoC, is a program to promote open-source software development. It has been organized by Google every summer since 2005 and it lasts 4 months, from mid-May to mid-August. Through this program, students contribute to open source repositories, with mentors and communities guiding them during the journey.
Personally, I also think it’s a fruitful way to spend the summer holidays.
What is “Developers Italia”
Developers Italia, created in collaboration between AgID and the Italian Digital Transformation Team, is the Italian community of public service developers. Have a lot of projects with the documentation that helps the integration of national enabling platforms in digital services.
Let’s Start
Google Summer Of Code has been a positive occasion for me in several ways. First and foremost, I had the opportunity to be advised by an amazing mentor who helped me overcome some of the major obstacles I found during the journey. Overall, this experience was full of highs and lows but, as I mentioned above, thanks to the support of my mentor and the Developers Italia community, I was able to convert the silence into insightful achievements.
The project consisted in implementing OpenAPI 3 support in “io-utils”, a typescript code generation tool actually working with Swagger 2 API specification.
OpenAPI is an Interface Definition Language (IDL) for describing and visualizing RESTful web services.
In every project phase, I improved the tool and cleaned the code while fixing existing issues and clarifying the library behavior under some specific circumstances.
I also had to convince the community about the changes I was making, so every fix, PR, updates of code was reviewed by the mentor together with some community members.
What does “io-utils” do
io-utils is a code generation tool used by the “IO” application, a large open-source software project developed by the Italian Digital Transformation Team which is currently in its beta phase.
The io.italia.it project aims at providing the possibility to potentially millions of people to interact with the Italian public administration by providing a set of services.
“io-utils” is used to generate the typescript classes from OpenAPI specifications. In detail, a set of API Specifications written in YAML or JSON format, are passed to the “io-utils” tool which generates JavaScript classes used to implement client and server code associated to the given interface.
Problems encountered
During this journey, I found many non-trivial problems. In the following paragraph, I will underline each of them and describe the solution I found.
Ensuring related projects don’t break
As io-utils is used by other projects, namely io-functions and io-functions-commons, I had to ensure that every change was backward compatible and give evidence to the community…
Fantastic “Continuous Integration”
To ensure that a code change does not result in a negative outcome for the overall state of the project it necessary to write and execute meaningful tests. However,
I found out that the steps needed in order to ensure such robustness require continuous repetitions which are redundant and time-consuming. The mentor suggested the use of CircleCI. I set it up on my forks customizing the build process. It was fun to learn about Continuous Integration
Recursively resolving Json Schema $ref —
After updating dependencies and improve variable typings I tested io-utils on related projects.
I noticed that nested schema references were lost during processing.
The problem was the recursive resolution of the references within the json schema that during the dereferencing of the document the link was lost.
As the npm module “swagger-parser” was not behaving as intended, the pre-GSOC openapi specifications were not conformant to the standard and modified to trick Swagger-Parser to give the desired output.
I tried two weeks to find new libraries and modify Swagger-Parser behavior, but then I recognized that:
- if I had fixed it in Swagger-Parser, I needed to wait for the Swagger-Parser community and I’d run out of time;
- if I wrote a new $ref resolver with Swagger-Parser low-level API, it would have taken too long.
Confronting with the mentor, we found a solution:
- we considered that the json $ref resolution was outside the scope of the GSOC and can be achieved via external libraries or tools, and we should focus on supporting OpenAPI v3;
- we decided that to maintain references between generated classes, the specification file should contain all the definitions. This can be achieved via standard OpenAPI tools written in other languages.
Project architecture
Architectural discussion in GH commits
Architectural discussions in GH
The original solution I proposed was to split the model by specification (Swagger 2 and OpenAPI 3) which would have in my opinion made it clean and maintainable over time, but the community decided to reuse and modify the existing model as it was already tested and working.
in the end, I found a suitable solution that made into the final PR (it is working but still not merged)
Every commit was backed by comments and a PR description and most of the discussion happened on the
Developers Italia slack channel
How to use/run io-utils
from 0 to hero
if you see errors, ask the community for help or open an Issue on Github repo
What did I learn?
I have learned and used many technologies, this is a list of new technologies that I learned/used for the first time:
- CircleCI (used for automation testing)
- Jest (used for testing)
- Nunjucks (used for a template for API)
Technologies that I have studied in-depth:
- TypeScript
- Yarn
- Gulp
- YAML
Acquired transversal / in-depth skills on:
- improved English language
- explain the problem in a simple way
What’s done?
- Everything started with this issue #91
- Fix yaml file PR started #93 and ended #94 [merged]
- Fix Swagger 2.0 Specs PR #380 [merged]
- important update for io-utils PR #107 [merged]
- Final PR to support completely OpenAPI 3 in io-utils, started #98 and continued #118 [completed, not merged]
- Update documentation PR #125 [waiting for merge]
What’s left?
- Merge PR #118 to master and publish a new major version on npm.
(after the review by the community, it will merge and then release the new version of io-utils)
Thanks to Roberto Polli and community for supporting me in this project.