API documentation service
Hi everybody!
I'm faced with the fact that I can't find a nice design service for publishing the API for my Rest service. So my idea is to create a service for API documentation publication (with nice design) for public access per reasonable price to let startups to get started. What do you think about it?
Well there will be primarily two aspect of the service that you are proposing.
Provide Management, Security, Authorization and versioning of the API docs. This will be the most complex thing to build for your use case. Also when you are dealing with username, email and passwords of your customers in a paid plan you need to take up securing them seriously. This might make you go to other cloud services and split your earnings. This is what the Swagger-Hub and friends do. The other choice is offer storing OpenAPI specs for free without any liability like https://apis.guru/openapi-directory/
Once you got your API Sepcs storage service sorted out, then you can display them by creating your own tooling if you see there is a compelling reason for people to use it instead of using other open-source tools
@nielsmouthaan has listed many of the OpenAPI viewers and I too have evaluated few of them on behalf of a fairly large organization dealing with thousands of API specs.
IMO [RapiDoc] (https://mrin9.github.io/RapiDoc/) takes is by far the best. Its is so very hackable and a joy to work with, supports [themes] (https://mrin9.github.io/RapiDoc/examples/themes.html) and have features that equates to Swagger-UI.
If you think that there is some lacking in these viewers then I would suggest to give it a try. The space is not much crowded in terms of good design
Interesting you found RapiDoc the best. I definitely see its potential but in terms of look & feel I think ReDoc does a far better job. I simply like the 3-column layout. But if you are looking for something similar to Swagger UI I understand your preference: it looks similar. Just out of curiosity, did you evaluated and considered ReDoc too, as that likely is going to be our pick (for a fairly large organisation too...).
Well we as a 6 member team evaluated 3 viewers (swagger, redoc, RapiDoc)
RapiDoc just dont offer Swagger Style view, they provide 2 different styles
here are the 2 views of the same spec
https://mrin9.github.io/RapiDoc/examples/read-mode.html
https://mrin9.github.io/RapiDoc/examples/example1.html
And on top of it they offer styling capabilities that no other tool so far we evaluated could offer.
But look and fee is something personal, so keeping it aside we found ReDoc to be lacking in many functionalities
Below are the issues that I remember that we found with Redoc
The only 2 drawback that we found with RapiDoc
Now we are kind of skeptical that RapiDoc has so many features and yet they are so little known, they have a tiny community and a very little github stars, so are we missing something.
In case you happen to critically evaluate RapiDoc, I will be very interested to know some of their cons compared to ReDoc and Swagger. As we are going to commit ourselves to use this tool for a very large audience base
I am evaluating a few services as we speak. AFAIK they all can take OAS3 as input (either directly or indirectly):
Quite a few of them, perhaps not all what you are looking for. My personal favourite so far is ReDoc as I really like the out-of-the-box look & feel, their usage is simple, have a nice CLI for bundling the docs and have easy customisation capabilities. Hope it helps.
We use Slite for internal documentation and Coda.io for external documentation. Coda has a new publishing feature and Slite recently started allowing for 'safe viewing' where it can't be modified.
I think some API's docs feel nicer than others, so if your tool builds better feeling documentation it could be good.
Here are API doc generators I found:
https://swagger.io/
https://github.com/slatedocs/slate
https://apidocjs.com/
Yes, I know this resources. Only swagger supports Open API v. 3.0 spec as I understood.
I want to offer a service with Open API 3.0 support.
The use case for API owner to develop a rest service which produces Open API 3 json response then point this endpoint to API Documentation service and get a nice documentation on the fly with no efforts.