Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

API Documentation Needs to be Simpler

DZone's Guide to

API Documentation Needs to be Simpler

The advent of Swagger has made Rest API documentation a much better prospect but we still have some way to go in deploying API documentation for our users.

· Integration Zone
Free Resource

Learn how API management supports better integration in Achieving Enterprise Agility with Microservices and API Management, brought to you in partnership with 3scale

I had an exchange with Abhinav Asthana (@a85), the Co-founder and CEO of Postman on Twitter today. He was tweeting about API documentation, and I chimed in with my support, about how we need to keep evolving our approach to delivering API documentation so that they speak to a diverse audience.

While I think we have come a long way with the introduction of Swagger UI, making learning about APIs much more interactive, and hands on, I think it's time to look at how we can further refine how we deploy API documentation for our users.

There is a lot going on with an API sometimes, and listing out all your endpoints, parameters, example requests, responses, and other elements can be overwhelming for new users who are just looking to learn the basics of an API, or possibly just get at s single resource, completing a specific action. 

Swagger UI, and similar API definition driven documentation like Lucybot API Console, do well in providing a comprehensive set of documentation for a potentially wide variety of API docs, but we need to keep scratching. I'm not exactly sure what the answer here is, but I'd love to see much simpler, embeddable, API documentation emerge. Solutions that allow API providers to display a small set of precise APIs, or possibly come up with some sort of slick user interface (UI), that delivers a simpler, more meaningful user experience (UX) that speaks to what a specific group of users is needing.

This is not a well-formed idea of mine but is something I want to get out early. I'm seeing an increase in the number of new API documentation resources lately, and hopefully I can influence at least one or two of their road maps with my ideas. This is one reason I've broken out my API documentation research out of my API management research. I have numerous ideas for new types of smaller, more bite-size API docs, as well as more embeddable, and visual API docs as well--having a research project setup gives me a single repo to think about, and publish these ideas.

Unleash the power of your APIs with future-proof API management - Create your account and start your free trial today, brought to you in partnership with 3scale.

Topics:
api ,process automation ,api design

Published at DZone with permission of Kin Lane, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

THE DZONE NEWSLETTER

Dev Resources & Solutions Straight to Your Inbox

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.

X

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}