DEV Community

Sharad Raj (He/Him)
Sharad Raj (He/Him)

Posted on

Tools for generating REST API docs rapidly?

So let's assume you have this REST API in whatever foo language, how will you document it if in hurry or you don't want to do complex things just for the sake of it.

Let's have a discussion and share resources (-.-)

PS: It's 11pm here so I may be on sleep mode after some time.

Discussion (10)

Collapse
drsimplegraffiti profile image
Abayomi Ogunnusi

Swagger will do magic....But postman documentation is divine

Collapse
sharadcodes profile image
Sharad Raj (He/Him) Author

I hear about swagger a lot

Collapse
janstepien profile image
Jan Stępień

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.

Collapse
sharadcodes profile image
Sharad Raj (He/Him) Author

I'll be reading this in depth, heard for the first time. Thanks for sharing this :)

Collapse
ryanleonbutler profile image
ryanleonbutler

Swagger UI and ReDoc is nice. Fastapi also uses both.

github.com/swagger-api/swagger-ui
github.com/Redocly/redoc

Collapse
jwbwater profile image
James Bridgewater

The ReDoc documentation for an API I worked with was very nice, easy to read.

Collapse
sharadcodes profile image
Sharad Raj (He/Him) Author • Edited on

I see this redoc more often than swagger when exploring REST APIs, probably because of the UI

Collapse
sharadcodes profile image
Sharad Raj (He/Him) Author • Edited on

I'm seriously considering making a theme with clean ui for this stuff which would be autogenerated for APIs. I mean seriously, not every project needs swagger, but maybe we are going a level higher every few months to be not considered as laid-back .. 😂

Collapse
vicradon profile image
Osinachi Chukwujama • Edited on

You should consider optic. It monitors your traffic and generates the endpoints and data associated with each end point.

Collapse
sharadcodes profile image
Sharad Raj (He/Him) Author

Oo.. Nice. Will try it out asap