You no longer need to write API docs by yourself: an Introduction to Testfully API Docs

Adam Wathan, the creator of Tailwind CSS, once said:

In open source, your documentation is your most critical marketing asset. Tailwind wasn’t the first of its kind by a mile but it was the first that anyone could really learn without basically reading the source. +

Although Adam talks about open source in particular, we can agree that when it comes to adopting a new framework, library, programming language, API, or anything else If people can’t learn it, they can’t use it.

I’ve been there, and I’m sure some of the readers have also experienced it — spending countless hours trying to figure things out about a new technology that does not come with decent documentation.

Good documentation is a sign of respect for your users.

Despite the importance of documentation, have you ever thought about why many APIs need more documentation? Given the importance of API Documentation for our users, why don’t we have great docs? Well, I’ve got a few reasons:

1. It takes time to write good documentation and maintain it over time
2. Many of us try to avoid it, just like leg days, because it’s not that exciting :)
3. Writing good documentation, just like any other thing, requires some skills and experience.
4. and many more …

Well, my friend, I’m very excited to share what we have been working on it for some time — our take on API Documentation.

Testfully’s take on API Docs

Like almost any other concept in API development, API Docs have different flavours. At Testfully, We believe that your HTTP requests have the information we need to generate API Docs, so why don’t we use them instead of hand-writing all of the docs ourselves? This is how it would work:

Testfully parses your request, and corresponding responses, extracts the metadata including endpoint, route and query params, headers, and request/response body and transforms them into state-of-art API docs for your users.

The diagram below demonstrates how a combination of standard HTTP request definitions in a Testfully workspace enables us to extract metadata of various endpoints and turn them into human-readable and interactive API documentation.

Click here to see the image in full size.

• Both “Fetch a list of users by country” and “Fetch a list of users by continent” requests use the [GET] /v1/users endpoint under the hood; hence they both contribute to the same endpoint documentation.

• “Fetch an existing user” and “Fetch a deleted user” endpoints leverage the same endpoint but with different responses, which enables the [GET] /v1/users/$userId endpoint to have docs for both 200 OK and 404 Not Found status codes.

Request & Response metadata

So far, we have mentioned the word “metadata” a few times, but we didn’t discuss what it means. However, that’s about to change:

For a request, metadata includes the underlying endpoint that serves a request, the params within the endpoint and their data type, any supported query string params and their data type, the request payload format and structure, and provided HTTP headers.

Using the above metadata, our API Docs can serve helpful information, including:

• Available API endpoints and their corresponding HTTP methods
• Query and route params for each endpoint, the expected format, and whether or not they’re optional
• The expected format for the request body including information about the type of each field and a human-readable description of each field within the request body.
• Supported authorization schemes for various endpoints

For a response, metadata includes the structure of the response, status code, and received HTTP headers.

Using the above metadata, our API Docs can serve helpful information, including:

• Expected response status code from each endpoint
• Corresponding API response for each status code, including information about the type of each field and a human-readable description of each field within the response body.
• Example response for each status code
• Expected response headers

The screenshots below show auto-generated request & response docs for the /v1/chat/completions endpoint of the OpenAI’s ChatGPT service.

Auto-generated with a twist

So far, we have constantly been talking about auto-generated API docs. By having auto-generated documentation, we can guarantee that your docs are always up-to-date with your actual API. That said, auto-generated does not mean read-only.

The API Docs feature auto-generates the documentation but always honours any manual change by your team and never overwrites them — unless explicitly asked to do so by your team.

A powerful editor allows your team to explore the generated docs, apply any changes, review any incoming changes from Testfully, and merge them into the “master” docs — it is a pull request system for your docs, just like Github.

Accessing API Docs

The documentation and editing capabilities will be available via Testfully’s desktop and web apps. In addition, docs will be exposed to your colleagues via three different channels:

Response Schema

Testfully’s Response Widget has already been updated with a new ” Schema ” tab. This tab hosts the schema of the request and response. It helps our users better understand the structure of the executed request and corresponding response.

Request Docs

Each request will have a dedicated page with auto-generated (with a twist) docs for that endpoint. The doc includes:

• Method and the API endpoint
• Supported route and query params, and their types
• Request payload, including metadata about each field
• Response, including metadata about each field
• Request and response headers

Endpoint Docs

This is where we merge documentation from multiple requests and generate docs for an endpoint. Multiple requests could contribute to docs for one endpoint. The doc includes:

• Method and the API endpoint
• Supported route and query params, and their types
• Request payload, including metadata about each field
• Response, including metadata about each field
• Request and response headers

Opt-in & Opt-out

We understand that different teams have different documentation requirements; that’s why we will have enough configuration for your workspace to let you decide what needs to be provided as API docs for your users.

Documentation Websites

We will take it even further and allow you to have a dedicated documentation website for your API’s internal and external users. Testfully provides an elegant way to provide custom content and edit docs to fit your needs. Furthermore, it will offer features including:

• Personalize the look and feel of the website to follow your brand guidelines
• Enable authorization for your website and give permissions to your partners
• Fully indexed and searchable docs for ease of access
• Interactive playground (powered by Testfully) to send requests
• Analytics for your website
• Import docs using Open API specification and other formats
• Version-controlled docs — have access to multiple versions of your API docs website
• Sample code for popular programming languages
• Ability to include custom content
• Ability to export data using Open API Specification, JSON schema, and other relevant formats
• and many more …

The Release Plan

I’m guessing you’re reading this paragraph because you’re interested in our approach, so let’s talk about our release plan for API Docs.

We anticipate releasing the complete version of API Docs by the end of 2023. We will release this phase in multiple features to receive feedback and iterate.

The table below outlines the delivery timeline for the API Docs feature.

The timeline is subject to change without prior notice.

Get involved

That’s about it for this blog post — it’s already much longer than I initially anticipated. I would love to hear your thoughts about what we’re building as part of our API Docs feature, so if you have suggestions or any feedback, please don’t hesitate to reach out via matt@testfully.io.

Thanks for reading this post!

Comments, Questions, or Feedback? Post it here!

• Write
• Preview

Powered by JamComments

Name Email Address Password

Submit

• Log Out

0 comments