Question

What's the best tool for building a customized API documentation?

Let's say you have an API you want to document and you want to:
- Let your users test their calls to the API thanks to a "playground" like the one on the Figma API
- Be able to customize it to match your brand guidelines
- Be able to customize its content easily. If I want to have a glossary on a specific page for instance.

Thanks in advance 😉

Mentioned
#Customer Support #Development #Figma
Share
forouzani's avatar
3 years ago

I would recommend using Redoc.
It uses swagger so pretty standard, is very feature rich, and can be easily customized to suite your needs.
You can build simple playgrounds with the Swagger Editor or you can drop in a repl if you want something more advanced.

Just remember that when it comes to API documentation... it's not about obtaining, it's about maintaining.

12 points
maguay's avatar
@maguay (replying to @forouzani )
3 years ago

"It's not about obtaining, it's about maintaining." That's so true for all documentation—it gets outdated so quickly!

1 point
ChucKN0risK's avatar
@ChucKN0risK (replying to @forouzani )
3 years ago

Hi @forouzani! Thanks a lot for sharing these tools. I will look into it. They seem to suit my needs 🙏

1 point
maguay's avatar
3 years ago

I checked with @adamd, a friend who's a developer evangelist and technical writer, and here were his recommendations:

  • Readme.com
  • Stoplight.io
  • APIMatic.io
  • Redoc (open source, redoc.ly is company version)

Some others, though less a focus for their company:

  • Postman
  • Swagger UI

Several open source frameworks, too, but they usually don’t focus on the interactive piece.

6 points
SharudAgarwal's avatar
@SharudAgarwal (replying to @maguay )
3 years ago

I think postman is actually extremely underrated for this. Their API doc generation is really good and has the obvious benefit of easy end-user testing since your customers can just download the collection. And it is easy to keep up to date because you likely use it yourself to test new endpoints or updates to old endpoints.

2 points
maguay's avatar
@maguay (replying to @SharudAgarwal )
3 years ago

Interesting, I've used Postman to test API calls, but never to build documentation. Didn't realize they had a tool for that! The "Run in Postman" button could be huge for building interactive API documentation.

Does it maintain documentation for older versions of your API as well?

1 point
SharudAgarwal's avatar
@SharudAgarwal (replying to @maguay )
almost 3 years ago

It basically just keeps your saved postman collection updated with your public documented collection. I haven't used it much other than showing people how our API works.
You can check it out here: www.postman.com/use-cases/developer-portals

2 points
iCanAutomate's avatar
3 years ago

I think Stoplight is really good and they keep improving the tool!

2 points
antl_io's avatar
a year ago

Hey Louis - Anthony from Bump here. I'd be curious to know what solution you went finally with and how it's going. Would love to connect!

1 point
mercurialsolo's avatar
3 years ago

We are on readme and really love the product in terms of finesse and the theme they bring to docs. On the downside they are fairly expensive.

We started with publishing an API ref off postman initially, and in early days it was definitely the way to go for us.

1 point
brnt's avatar
3 years ago

Another one worth looking at is Slate, which we use at my startup - https://github.com/slatedocs/slate

It's on the simpler side of the complexity spectrum. It lets you write the docs in extended Markdown syntax and it gives you basic branding customization capabilities.

No playground support though.

1 point
maguay's avatar
@maguay (replying to @brnt )
almost 3 years ago

Ohh that looks super nice, thanks for sharing! Was it reasonably easy to get code samples lined up with the relevant documentation?

1 point
What are the best platforms for community management?

We have 15k newsletter subscribers, and have around ~2k of them in a Slack group. We're starting to encounter issues in terms of community management - specifically, it's hard to pin content like c...

Any suggestions for a workaround to an Outlook calendar not syncing with Google Calendars?

Google lets you subscribe to a calendar using a URL - although when using an Outlook 365 Calendar link, events are copied over once, and then the syncing stops. This seems to be a relatively new is...

The community for Figma  power users.