Find next API documentation tools

[alexgarel]

As stated on may 19 meeting our first job is to try to find the best tools for the job.

If possible a tool (or set of tools) that met as much requirements as possible:

• open-source if possible, at least free to use
• have documentation near the code (code change and documentation changes in same PR if possible)
• make github review of changes possible
• have OpenAPI compatibility (be able to have the API in open API format)
• have a testable documentation (this would be implemented later)

[alexgarel]

@Roxie-32 here is my personal search from yesterday:

I've seen no markdown or other format to OpenAPI documentation. Every where there are import of OpenAPI in another documentation framework (like gitbook / slate). It lead me to think we have to find a good tool to generate or edit OpenAPI documentation.

• Postman can already export to OpenAPI (eg. postman-to-openapi)
• there are specialized editors that renders a preview like Swagger Editor, and it seems acceptable to me, particularly if we use yaml. There is also a vscode extension It has the advantage of really being a tool to write code, so really integrates well with git process

Even if we do OpenAPI I think we will need to integrate it in a larger documentation framework. We mentioned gitbook yesterday and I've done a quick search for open-source alternatives.

• https://rust-lang.github.io/mdBook/index.html is a fork of gitbook. It only provides a CLI, not the nice rich text editor of gitbook. But vscode, for example, as good support for markdown with preview.
• slate is another API doc generator with existing importers (widdershins, swagger-to-slate)
• I see that other popular tools like sphinx have similar plugins
• docusaurus also seems like a good open source alternative and has openapi plugin

If we want to stick with postman, but be reviewable in github, we can imagine requiring (via an action) an openapi export on each PR.

My only solid take-away:

• we need to have open-api files
• we need another framework to generate documentation from markdown files (or the other way around)

[satokenta940]

If it's free, Apidog is free. I'm not sure if you've found the right tool, but if not, I think it's pretty good.

[Haywhyhoo4]

Hi @teolemon I am interested in the Find next API Documentation tools, I am seeking more clarification as regards the issue. cc @alexgarel .