Taking Setu docs to the next level: Phase 2

Setu is reimagining and redeveloping the future of its documentation. We are reinventing the mechanisms in phases. To know more about how we began this journey, check out Phase 1.

Visit our docs

Onto the next ladder step with Phase 2.

Documentation is of paramount importance at Setu and we are suckers for great documentation

What is next level ?#

For anything to go to the next level, we need to first identify problems on this level and solve them.

Is that it?

Well, to define is to limit, right?

Problems on this level#

After the launch of Phase 1, we saw an increase in the number of people contributing to our docs. The process is asynchronous, people are getting familiar with Git, and Lightyear is doing its magic. With things starting to look good on that side, next comes our API references.

API references provide developers with in-depth knowledge of an API

API reference talks about the structure, parameters, request-response samples, and methods in it. It’s like a handbook for developers that contains all the necessary information when integrating with APIs.

At Setu, API references for different products were scattered, few products used Postman, and few used Redoc. We wanted to bring consistency in the experience of our API reference for developers across all products.

API references setup#

For Postman#

Product teams using Postman created a collection with all the APIs and updated them accordingly. Using Lightyear, they can add a redirect to this Postman collection from our docs. Postman did help us in certain aspects like:

• Easily import collection of APIs

• Add examples for different scenarios.

• Environment variables, pre-request scripts, and write test cases.

• Testing of APIs was very simple. This is a very important aspect, also the reason we love Postman and we want to test APIs on our docs too. (more on this, soon 😉)

Postman provided the right tools for developers integrating with our APIs not all of them. It's not entirely an API reference and cumbersome for teams to add the details of APIs on what type the parameter is, their descriptions, constraints like Required, valid values, etc.

For Redoc#

Using Lightyear, we can add OpenAPI specifications inside the MDX files and our Redoc component will render the provided specifications.

Redoc solves exactly what Postman couldn’t solve but it doesn’t have the tools that Postman has.

Both Redoc and Postman take the end-user away from our docs to an entirely new experience and it can be jarring at times.

Phase 2#

Considering all the above scenarios, this shouts hugely for an intersection of both the solutions we have at Setu. Taking the best bits of Postman and Redoc, we implemented an in-house API reference experience.

Lightyear API references is an API documentation tool built in-house at Setu that parses and renders the OpenAPI specifications using our design components which adds that extra Setu touch to this whole thing. This is an UI component added to the family of tools in Lightyear

Try out a few product API references, here and here.

Code Snippets#

Lightyear API provides developers with code snippets of multiple languages. They can now just copy the code snippet with the language of their choice and get started.

We started with cURL, Node.js , Python and Go with plans to add more in the future.

API references are now public#

We decided to publish API references of all the products on our GitHub under MIT license. Check them out here.

Product teams can update API references directly on our GitHub and we're also working on a pipeline using GitHub Actions to make this process automated.

---

By introducing a unified API reference experience across products, we began the journey of striving towards consistency and also opening an opportunity to build tools needed for developers to test our API references. We're confident that this is a starting step to achieving the vision we have for our docs in the long run.

What’s next?#

This is an ongoing process and we’ll be back with what happened in Phase 3 when it goes live.

As said in Phase 1 regarding open-sourcing Lightyear, we're on track to do it and watch out this space for more exciting tools we're building with our docs.

There are plans to open-source the Lightyear API references component, so that anyone can pass an OpenAPI specification file/URL and render it in docs accordingly.

We’re also hiring across the board. Go over to setu.co/careers to apply or write to careers@setu.co if you have any questions.