SinV
TTCTheo's Typesafe Cult
•Created by SinV on 4/25/2023 in #questions
Best practices/tools for generating OpenAPI and documentation
I'm doing a spike on refactoring some services and looking to add a build script/step that auto-gens the OpenAPI documentation (ideally plus static sites) for the front-end team to consume.
The back-end is in C# for reference, and thankfully the .JSON spec gen has been handled through NSwag. What I'm looking for now is clean MD files and hopefully a static site generator.
So far I've found tools like https://github.com/Mermade/widdershins (or https://www.npmjs.com/package/openapi-to-md) and https://github.com/slatedocs/slate that cross most of the goalposts, my concern right now is that there isn't a lot of active maintenance on some of these projects, and some of the documentation leaves a bit to be desired.
In general I'm wondering if anyone has some best practices or tools when dealing with multiple types of back-ends, front-ends, and related documentation between teams on this kind of development.
4 replies