The Easiest Ways to Generate API Documentation

—

by

Mario
in

the-easiest-ways-to-generate-api-documentation

As a developer whether you are a web developer or app developer, you may be familiar enough with API documentation. API documentation is an important part of the product offering affordances to the developer community to help them understand exactly what an API offers and how to use it. Below are several hints that you can use to create API documentation easily:

What API Documentation Should Contain

You can create your own API Documentation as you like, since there are no standards on what API documentation should encompass. The important thing is makes it easy for them to understand an API is a good starting point. However, you can follow the list below from established providers in the API economy:

  • A list of the resources with an explanation of the purpose of each in the context of the product or service being offered via the API;
  • Examples of API calls in a variety of languages and tools (cURL, Postman Collections, etc.);
  • Do something meaningful in the context of the product or service the API offers, guides that detail the workflows implicit in using the API i.e. the sequence of API calls. For example, Dwolla offers several guides on how to send or receive money, with branches into different contexts throughout that explain the different aspects of their product offering;
  • An overview of the design principles adopted by the API provider and what that means for aspects adherence to REST (especially hypermedia), HTTP codes, etc.;
  • Information on authentication, including schemes that may be implemented such as OAuth or OpenID Connect;
  • General information on error handling with information on the HTTP return codes that will be returned;
  • User-specific contexts that help developers get to grips with the subject matter more easily. For example, Stripe automatically tailors their API documentation with your API key and secret (when you are logged in) so any code samples are immediately ready to use;
  • An interactive API explorer that allows the developer to readily bring all this information to life.

Interactive Explorers

It is a common thing to have an Interactive Explorers in API specification formats generated from the specification document itself, creating a means for consumers to both learn about and test API calls at the same time. With the help of interactive explorer in understanding a provider’s API, publishing API will be easier. The options are therefore largely dictated by the choice of API specification format, for example:

  • The OpenAPI Specification (aka Swagger) offers Swagger UI, which allows you to generate an interactive explorer with virtually no coding (depending on the completeness of your Swagger specification);
  • Apiary offers an explorer that is generated from API Blueprint and Swagger specifications. It mixes the features of an interactive explorer with a documentation suite as it renders the Markdown documentation in API Blueprint side-by-side with an interactive tool for making sample API calls;
  • Finally, an open-source explorer is offered for the RAML specification format that implements many of the same features as Swagger UI and Apiary.

By using these tools, we hope you can create an easy-to –use reference point for their developer community. However, static documentation may be required to accompany an interactive explorer, if the subject matter of the API is complex or requires high-level explanation not necessarily associated with a resource.