search

PaloAltoNetworks / docusaurus-openapi-docs

🦝 OpenAPI plugin for generating API reference docs in Docusaurus v3.
https://docusaurus-openapi.tryingpan.dev
MIT License
699 stars 233 forks source link

Unclear whether the plugin CLI is required or optional #910

Closed imnotashrimp closed 1 month ago

imnotashrimp commented 2 months ago

Documentation link

https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/main/demo/docs/intro.mdx?plain=1#L238

Describe the problem

Here, the statement is "the CLI can be used to generate and clean API docs." I can't tell from this wording whether the CLI is optional or required.

I also found an issue comment here ("You didn't specify that you actually ran the CLI command to generate the docs from the api plugin. In case you didn't, you would run..."), which makes me think the CLI is required before running docusaurus build.

So the problem is: I think the CLI is required, but I can't tell from the documentation whether that's the case.

Suggested fix

  1. The statement I quoted above should be clarified.
  2. If the plugin CLI is a prerequisite to building the Docusaurus site, the required flow (generate API docs with the CLI, then docusaurus build) needs to be explicitly stated and made much more visible.

I'm happy to open a PR once I know what the required steps are.

sserrata commented 2 months ago

Hi @imnotashrimp, the CLI is indeed required for generating/cleaning API docs.