Our great sponsors
-
-
SurveyJS
Open-Source JSON Form Builder to Create Dynamic Forms Right in Your App. With SurveyJS form UI libraries, you can build and style forms in a fully-integrated drag & drop form builder, render them in your JS app, and store form submission data in any backend, inc. PHP, ASP.NET Core, and Node.js.
-
openapi-generator
OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)
-
-
-
redocly-cli
⚒️ Redocly CLI makes OpenAPI easy. Lint/validate to any standard, generate beautiful docs, and more.
-
-
WorkOS
The modern identity platform for B2B SaaS. The APIs are flexible and easy-to-use, supporting authentication, user identity, and complex enterprise features like SSO and SCIM provisioning.
The first iteration involved adding a small build script to the docs repo that cloned the backend repo and used swagger-markdown on each file to generate markdown. Docusaurus found the markdown files and did the rest.
Widdershins 👎
OpenAPI Generator 👎
Our specs were split between several YAML spec files. It looked like a good idea when we did that - large files are not fun to work with. The problem is that very little in the OpenAPI ecosystem was built for multiple files. I strongly recommend that you will save yourself the pain and go the mono-file route. If Stripe can have a 4.5MB spec file, so can we.
In order to use Redocusaurus, I needed a single spec file. Both Swagger cli and OpenApi cli offered an option to merge separate specs into one. The problem was that one of them required a "root spec file" to drive the merging and the other required extra information to resolve conflicts. My specs had neither.
In order to use Redocusaurus, I needed a single spec file. Both Swagger cli and OpenApi cli offered an option to merge separate specs into one. The problem was that one of them required a "root spec file" to drive the merging and the other required extra information to resolve conflicts. My specs had neither.
It started with a very simple setup. Two github repositories: One for our backend, which included OpenAPI specs of our backend APIs. The second for our documentation website, which we based on Facebook's Docusaurus.