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!
Niklas Winkels
in progress