OpenAPI Specification Generator
in progress
Niklas Winkels
Easily generate OpenAPI v3-compliant documentation for your Strapi APIs. We’re building an official OpenAPI specification generator to help developers streamline integration, enhance documentation, and unlock powerful tooling across the Strapi ecosystem. This new CLI-based tool will output an OpenAPI v3-compliant spec for your Strapi project—including core APIs, custom endpoints, and plugins. With support for customization hooks and
x-strapi-
extensions, it ensures the output reflects your exact API structure and configuration. This will also lay the foundation for generating client libraries, TypeScript types, and more robust API workflows.Seth Campbell
I am very excited to see this in progress and have a couple of thoughts/questions.
First, has there been any thought of how to handle deeper populated return types? As of right now, with the existing plugin, the OpenAPI spec generates return types without regard to the "populate" query parameter (and I assume similarly for other query params).
If I understand correctly, this is a limitation with OpenAPI specs in general -- not being able to add definitions based on the value of query parameters. Would it be possible to add these extra fields as optional within the spec, or some other solution?
Right now, using the existing documentation plugin, if I use "populate" I have to do type casts on the deeper fields since the generated types do not include the fields by default.
Second, I often will use a dynamic zone with a limit of 1 component, similar to how you can have a field that is a single component. Right now, the return type is still an array (I.e. if the dynamic zone is limited to components A, B, and C, with a maximum of 1, the type for the field will be (A | B | C)[]. It would be a big QOL improvement if it were simply "A | B | C | null" or just "A | B | C" if the dynamic zone is required to have exactly 1 component.)
Perhaps that would make a greater difference if dynamic zones could have the choice of being for a single component, or repeated components like you can for component fields, although that would certainly be beyond the scope of this task.
Anyways, thanks for working on this task, it will be greatly valuable!
J
Jamie Howard
Seth Campbell
Hi, great to hear you're looking forward to this functionality!
1) if I follow you rightly here you're suggesting tracking different return types in the open API spec based on the presence of different query params?
The Open API spec generated by the new package will be much more accurate with it's return types. But to track different return types based on different query param combinations isn't feasible. It would be very challenging technically and the specs could grow significantly.
2) The intention of dynamic zones from a product perspective is that they can expand and therefore an array seems like the best representation for them. Just using a single component seems like a good alternative to a dynamic zone limited to length = 1 ?
Keep an eye out for the beta of the open API package in the next few weeks.
We'd love to hear any feedback in the relevant repos:
https://github.com/strapi/strapi/issues
https://github.com/strapi/client/issues
Niklas Winkels
in progress
J
Jamie Howard
...