gen-api-docs does not regenerate files when the openAPI spec changes

[shmichael]

Describe the bug

When creating the openAPI schema, It would be convenient to allow regenerating MDX files as the openAPI schema changes. Currently, when I change the schema and run gen-api-docs, no existing MDX files are updated. This requires running clean-api-docs and then re-running gen-api-docs. When the docusaurus dev server is running, it causes it to reload after the MDX files are deleted and then inconsistently again once they are generated. So I cannot trust it is in the latest state and have to restart it every time.

Expected behavior

I would expect gen-api-docs to produce the same output regardless of whether clean-api-docs was previously performed.

Current behavior

gen-api-docs will not update existing MDX files even if the underlying schema has changed.

Possible solution

Provide a flag to always overwrite MDX files, or make it the default behavior.

Steps to reproduce

1. Create an OpenAPI spec file
2. Generate MDX files using gen-api-docs
3. Start a dev server (docusaurus start)
4. Change the OpenAPI spec file such that an existing file would change (e.g. change the "info" section)
5. Re-run gen-api-docs
6. Observe gen-api-docs does not report any changed file
7. Check whether the MDX file is updated.

Context

Currently, I need to restart docusaurus dev server every time I change the schema. This takes ~30 seconds. Instead I could regenerate files and refresh in ~1-2 seconds.

Your Environment

• Version used: 2.0.0b3
• Environment name and version (e.g. Chrome 59, node.js 5.4, python 3.7.3): node v20.3.1
• Operating System and version (desktop or mobile): Windows WSL 2
• Link to your project: Private

[welcome-to-palo-alto-networks[bot]]

:tada: Thanks for opening your first issue here! Welcome to the community!

[restyler]

100% agree, the development ergonomics suffers greatly now - minimal change in OpenaAPI spec requires 30+ seconds and multiple commands in terminal to view it in browser... In my case, npm run docusaurus gen-api-docs all does not detect the updated openapi spec at all. so my current workflow is: stop docusaurus dev server; run npm run docusaurus clean-api-docs all && npm run docusaurus gen-api-docs all; start dev server again. May be it's me doing it wrong?

[restyler]

After I have commented out the if (!fs_1.default.existsSync(`${outputDir}/${item.id}.api.mdx`)) {

condition in

node_modules/docusaurus-plugin-openapi-docs/lib/index.js - it allowed me to achieve what I needed - I don't need to run clean-api-docs anymore to make gen-api-docs generate files, and dev server now detects the changes in generated mdx properly, so I can update my openapi spec much faster:

(obsiously we need to change the source line in .ts, but I am not sure this does not have any unpleasant side effects yet)

[sserrata]

Hi @shmichael, I think what you're asking is if the plugin can effectively overwrite generated files, thereby eliminating the need to run "clean" in between changes to the OpenAPI spec.

It's something we've considered in the past but we also wanted to be careful not to miss changes to the OpenAPI spec that should otherwise require a "clean", like removed/deprecated endpoints and renames. That said, it's probably still possible to support overwrite as along as it's clear to users that some changes to the spec will require a "clean" to remove "orphaned" files.

[shmichael]

Hi @shmichael, I think what you're asking is if the plugin can effectively overwrite generated files, thereby eliminating the need to run "clean" in between changes to the OpenAPI spec.

It's something we've considered in the past but we also wanted to be careful not to miss changes to the OpenAPI spec that should otherwise require a "clean", like removed/deprecated endpoints and renames. That said, it's probably still possible to support overwrite as along as it's clear to users that some changes to the spec will require a "clean" to remove "orphaned" files.

Yes, I think a naive implementation would blindly overwrite potentially leaving stale artifacts. In such case I would make it an explicit flag that the caller must turn on.

A cleaner solution would be to compute the full tree of generated files, compare it to the existing files (i.e. dry-run of clean) and then perform all necessary modifications including removal of stale files. In such case I think there would rarely be undesired side effects and the operation would be much faster.

[sserrata]

@shmichael, in your proposed solution, how could you distinguish between operationId/summary renames vs adding/removing an operationId/summary?

[shmichael]

@shmichael, in your proposed solution, how could you distinguish between operationId/summary renames vs adding/removing an operationId/summary?

I might be missing some important context here, but I don't see the material difference between the two. Let's say we have a certain operation and we rename it. The result is one mdx file needs to be deleted (old name) while a separate one generated (new name). This would be the exact same effect if we deleted the old operation and introduced a completely new operation.

In the "naive implementation" case, any rename or delete would leave residue. In the "clean implementation" it would be handled just like clean-api-docs + gen-api-docs today. Even the "naive implementation" would be useful for development because this residue is typically not checked in (we personally generate mdx as a deployment script) and won't be linked into the sidebars.

[Doron-Bargo]

Hi, any update on this issue?

[sserrata]

Hi @Doron-Bargo, no updates. FWIW, out API doc writers simply run a "clean" script/command as needed, between changes. If this is too cumbersome you could add a clean step to your start and/or build script in package.json. Ultimately, our docs team doesn't check in the generated files which helps ensure the docs always reflect the latest changes to the spec(s).