GSoD 2020: Week 5 to Week 7

The phase 2 of Google Season of Docs 2020 started. In the fourth week, when I was done with PCP books, I started with the REST API Guide documentation. The PCP REST API was documented in man page format. This was not ideal for web developers, so it is needed to transition to separate formatted web pages describing individual requests, allowed inputs, sample outputs, etc. Likely, this would also be in RST form such that it can be hosted on the modern, community readthedocs.io site. This will also allow community contributors to more easily change and extend this content.

For documenting the REST APIs, my mentor had suggested me a new tool- Swagger. It was completely new to me. I spent the fourth week learning and implementing Swagger. I encountered several challenges during this phase. But, the odds was is in my favour.

In the fifth week, when I started writing the REST APIs documentation in Swagger, I encounterd many challenges. One of the major challenge was - how to intergrate Swagger with sphinx? But, my mentor found a solution for this - sphinxcontrib-redoc. This Sphinx extension renders OpenAPI (fka Swagger) specs using amazing ReDoc. Another challenges include - how to write long text into description, how to show more than one responses for a single API. But, I overcame all the challenges and implemented the OpenAPI spec format in no time. I completed the conversion of Open Metrics API, Scalable Time Series APIs, Full Text Search APIs in this week. My mentors was very happy from my work since I learnt and implemented all these things just in one week.

Now, I had travelled the three-fourth path and only one-fourth path was remaining. In the sixth week, I completed the last part of REST API Guide - PMAPI host services API. In the end, prior to sending PR, I sent the demo repository link to the mentors for the review and while reviewing the REST API Guide work, my mentors had shown a huge satisfaction.

In the seventh week, after implementing all the suggestions/feedbacks from the mentors, I opened the PR. In the end, the REST API Guide was hosted on the rtd site and they were looking very very beautiful, neat and awesome.

Please have a look here.

All the credit goes to my mentors for suggesting me that awesome tool - Swagger and helping me throughout the challenges to accomplish the task. So, the phase 2 was challenging, fun-learning and completed now and I was heading ahead for the phase 3.

References: Swagger, sphinxcontrib-redoc, ReDoc, OpenAPI