docs: update OpenAPI generation docs (#4951)

howtos/interactive-api-explorers.md

@@ -2,29 +2,37 @@
 
 The docs include an interactive explorer for some of the Camunda APIs. These explorers are generated with [a Docusaurus plugin](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/), based on an OpenAPI specification file.
 
-Each explorer is configured in `docusaurus.config.js` ([example](https://github.com/camunda/camunda-docs/blob/f71d68e0fa6681d334e4fd1bf86a077f456f35f0/docusaurus.config.js#L151-L169)). The docs for these APIs are generated directly into the main docs instance, in the Next version only. As minor versions are released, the docs for the Next version are copied to the current version of the docs. In this way, these APIs have versioned documentation.
+Each explorer is configured in `docusaurus.config.js` ([example](https://github.com/camunda/camunda-docs/blob/708bc4dbc6a8a2aeae324ab86ff4e59cc74c59fa/docusaurus.config.js#L193-L219)). All API explorers are generated directly into the main docs instance.
+
+The configuration can include multiple versions. The Next version docs are generated based on the spec located in the root `api/[apiName]` folder. Each numbered version's documentation is generated based on a spec located in the corresponding `api/[apiName]/[version]` folder.
+
+As minor versions are released, the docs for the Next version are copied into the new "current" version of the docs. The docs team will adjust the configuration to also support documentation generation for this new version.
 
 ## Source files
 
 The source for each API's instance lives in an identifying folder within the `/api` folder. Following is a description of the contents of these folders.
 
 - `/api/[apiName]/`: Home to the API Explorer source/configuration.
-- `/api/[apiName]/[apiName]-openapi.yaml`: OpenAPI spec for the API.
+- `/api/[apiName]/[apiName]-openapi.yaml`: OpenAPI spec for vNext of the API.
 - `/api/[apiName]/generation-strategy.js`: A JavaScript file that describes custom steps required to standardize this API's explorer.
   See `api/generate-api-docs` for details on how this file is used during the generation process.
+- `/api/[apiName]/[version]/[apiName]-openapi.yaml`: OpenAPI spec for version `[version]` of the API.
 
 ## Updating an OpenAPI spec
 
-The OpenAPI spec is only used to generate the API Explorer for the Next version of versioned explorers. This can be done in synchrony with alpha releases, to give users a preview of the new API features.
+### Regenerate the docs for the Next version of an API
 
-For non-Next versions, the previously-generated documentation is copied into the versioned doc folder, and changes can and should be made directly to the markdown files.
+1. Replace the OpenAPI spec file at `/api/[apiName]/[apiName]-openapi.yaml`.
+2. Regenerate the docs with this command:
+   `npm run api:generate:[apiName]`
+3. Commit the changes, and open a PR.
 
-To re-generate the Next version:
+### Regenerate the docs for a numbered version of an API
 
-1. Replace the OpenAPI spec file at `/api/[apiName]/[apiName]-openapi.yaml`.
-2. Regenerate the explorer with this command:
-   `npm run api:generate:[apiName]`.
-3. Commit changes, and open a PR.
+1. Replace the OpenAPI spec file at `/api/[apiName]/[version]/[apiName]-openapi.yaml`.
+2. Regenerate the docs with this command:
+   `npm run api:generate:[apiName] [version]`
+3. Commit the changes, and open a PR.
 
 ## Code languages