So far, we have followed a test-driven approach to developing our User Directory application. We started by writing End-to-End (E2E) tests and using them to drive the development of our implementation code, and then added unit tests to catch regressions. We have also discussed that writing tests is the best form of documentation, since it provides actual examples of how to interact with our API.

While our test suite is the most accurate and best form of documentation, providers of all major APIs also maintain browser-based API documentation that your end users can access as a web page/site. This is because:

• Not all APIs are open-sourced, so developers may not always have access to the tests.
• It may require a lot of time and effort to understand the test suite.
• Tests lack context—you know how to call an endpoint, but you will have to figure out for yourself how it fits into the workflow of an application.
• It is language- and framework-specific—the browser-based documentation describes the interface of the API, not the implementation. It doesn't matter if our API is implemented in Express, Restify, Hapi, or in Python or Go. The end user does not need to understand JavaScript in order to understand this form of documentation.

If we simply provided the test suite for our end users without further guidance, they are likely to be deterred by the steep learning curve and decide to use an alternative service. Therefore, we must provide more user-friendly API documentation.

An API documentation describes, with examples, the functionality of each endpoint, and the constraints when calling them. Good API documentation usually:

• Provides a high-level overview of our API, including:
  • A brief overview of the platform
  • Example use cases
  • Where to find more resources and/or receive support

• Includes a concise step-by-step guided tour on how to perform common scenarios (e.g. create a user, and then log in); that is, which API calls needs to be made, and in what order.
• Includes an API Specification, which provides technical references of each endpoint—what parameters are allowed and in which format.

Authoring of the high-level overview and the guided tour falls under the scope of a Technical Writer. But what makes a good piece of technical writing is beyond the scope of this book; instead, we will focus on how to write a good API specification. Specifically, we will be using the OpenAPI API specification language to write our API specification, and then use a set of tools called Swagger to generate an interactive browser-based API reference.

By following this chapter, you will:

• Learn about the OpenAPI Specification (OAS)
• Write your own OpenAPI specification in YAML
• Use Swagger UI to generate web-based API documentation