Whenever your API receives a request with Accept: text/html you respond with a static HTML file. It documents the resource available at the requested path. Your resources become self-documenting.
The HTML files can link to other resources served by your API. This makes it easier to navigate the entire documentation in a web browser.
I like this approach for its simplicity. It doesn't need any library and it works in every framework. Its main weakness is maintainability; the documentation won't keep itself up to date automatically.
You can use content negotiation.
Whenever your API receives a request with
Accept: text/html
you respond with a static HTML file. It documents the resource available at the requested path. Your resources become self-documenting.The HTML files can link to other resources served by your API. This makes it easier to navigate the entire documentation in a web browser.
I like this approach for its simplicity. It doesn't need any library and it works in every framework. Its main weakness is maintainability; the documentation won't keep itself up to date automatically.
I'll be reading this in depth, heard for the first time. Thanks for sharing this :)