alexgarel
commented
2 years ago @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
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: