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.
GitHub
GitHub - Mermade/widdershins: OpenAPI / Swagger, AsyncAPI & Semoasa...
OpenAPI / Swagger, AsyncAPI & Semoasa definitions to (re)Slate compatible markdown - GitHub - Mermade/widdershins: OpenAPI / Swagger, AsyncAPI & Semoasa definitions to (re)Slate com...
GitHub
GitHub - slatedocs/slate: Beautiful static documentation for your API
Beautiful static documentation for your API. Contribute to slatedocs/slate development by creating an account on GitHub.
1 Reply
https://nordicapis.com/7-open-source-openapi-documentation-generators/
https://github.com/swagger-api/swagger-ui/
https://github.com/Redocly/redoc
These ended up being the solutions I went for the most, with Swagger UI taking the lead as it was being used in tandem with the C# backend tooling
Vyom Srivastava
Nordic APIs
7 Open-Source OpenAPI Documentation Generators | Nordic APIs |
Here we take a look at some free, open-source tool options for generating docs from an OpenAPI v3 file. Redoc, WidderShins, SwaggerUI, DapperDox, LucyBot, RapidDoc, and OpenAPI Viewer make the list.
GitHub
GitHub - swagger-api/swagger-ui: Swagger UI is a collection of HTML...
Swagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API. - GitHub - swagger-api/swagger-ui: Swagger UI is a col...
GitHub
GitHub - Redocly/redoc: 📘 OpenAPI/Swagger-generated API Reference ...
📘 OpenAPI/Swagger-generated API Reference Documentation - GitHub - Redocly/redoc: 📘 OpenAPI/Swagger-generated API Reference Documentation