PaloAltoNetworks / PaloAltoNetworks/docusaurus-openapi-docs

Add flag to re-write sidebar.js (and other auto-generated files)

Open
#983 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
TypeScript
Stars
1.1k
Forks
315
Avg merge
7d 5h
Merged PRs (30d)
7

Description

Is your feature request related to a problem?

Similar to https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/issues/615#issuecomment-2197534877, I noticed that changes to the OpenAPI specs aren't reflected in sidebar.ts file: https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/00631740bd7a06d447ed7eb2aa4b7b7259593e71/packages/docusaurus-plugin-openapi-docs/src/index.ts#L181-L194

I think it would be nice to add an --overwrite arg in CLI that would allow you to overwrite this!

Describe the solution you'd like

Something similar to docusaurus gen-api-docs <plugin_id> --overwrite

Describe alternatives you've considered

Not blocked, able to just clean/delete the repo but it would be a nice step to include. It wasn't super obvious to me when I first did this and spend some time trying to debug why my updates weren't appearing in my docs.

Perhaps also maybe in output text say "warning: OpenAPI spec differs from data currently saved in <destination_path>.sidebar.ts file. If you would like to update this file, please re-run with the --overwrite flag: docusaurus gen-api-docs <plugin_id> --overwrite"

Additional context

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in packages/docusaurus-plugin-openapi-docs/src/index.ts around lines 181-194, where generated sidebar.ts output is handled, and trace the docusaurus gen-api-docs CLI arguments. Add the requested --overwrite behavior and warning for differing generated files; done means updated OpenAPI specs can regenerate sidebar.ts and other auto-generated files without manually deleting them.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, typescript
Domain
cli, documentation, tooling
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.