Zulip GSoC ’18 Progress Log
is a link to a list of all my commits in Zulip repositories along GSoC.
Week 1 — 2018/05/14
GSoC has begun! As discussed with Tim, I took care of a few tasks in the +Roadmap for "REST API” docs which I had started during the community bonding period.
Then I began to document endpoints, starting with /users/me/<stream_id>/topics. This involved a few things: adding support in our Python and JS bindings, and the documentation itself (using the new API docs ecosystem). This also involved some fixes here and there.
Also, after having a hands-on experience with the new documentation procedure, I discovered some steps that could be optimized to keep things simpler and avoid duplicating work.
I discussed some of my concerns with Tim and Eeshan, and we agreed that we could try OpenAPI as a format for storing our REST API docs.
That’s when I started to work on a system that could implement parsing OpenAPI files into the docs’ template system.
Week 2 — 2018/05/14
Along the process I faced some issues when parsing files: mostly stuff that was specific from OpenAPI (and therefore it wasn’t already implemented in any standard YAML parser).
Since those OpenAPI-specific features were exactly what made worth switching to the OAS (OpenAPI Specification), I decided it was worth creating ourselves.
The first of this OAS features I had to implement was JSON references: in order to insert content from other parts in the local file (or even external files), you can use a $ref tag with a .
That’s how was born: with the goal of resolving those references inside a YAML file. Since I considered that it might be helpful to other people, I uploaded it to a separate repo and published it as a PyPI module with the same name.
The second feature is the allOf key, which takes a list of objects and merges them into a single one. For instance, in the following example:
- $ref: '#/components/schemas/NewPet'
Pet should become: