Zulip GSoC ’18 Progress Log

Overall work

This is a link to a list of all my commits in Zulip repositories along GSoC.

Weekly report

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 JSON reference.
That’s how yamole 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:

components:
  schemas:
    NewPet:
      required:
        - name
      properties:
        name:
          type: string
        tag:
          type: string
    Pet:
      allOf:
        - $ref: '#/components/schemas/NewPet'
        - required:
          - id
          properties:
            id:
              type: integer
              format: int64

Pet  should become:

Pet: