Chapter 13. Documenting Our API
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...