When will 3.0 be available?

[tjperry07]

Genuine question, I want to use this for my 3x Docusarus site. But it's not slated until like July or something, I'll grab Redoc.

I did try to install the beta version, but it doesn't actually install anything. None of the package.json commands or even appear in my node modules folder.

[sserrata]

Hi @tjperry07, you're welcome to try the latest beta release, which supports Docusaurus 3.1.1. How did you try installing? Can you share your reproduction steps?

[sserrata]

Hi @tjperry07, installing the packages won't update your package.json scripts. Installing docusaurus-plugin-openapi-docs will extend the Docusaurus CLI to include commands for generating and cleaning OpenAPI docs, but only after you've configured the plugin in docusaurus.config.js:

% projects/panw/my-3.0-test yarn docusaurus -h
yarn run v1.22.19
$ docusaurus -h
Usage: docusaurus <command> [options]

Options:
  -V, --version                                            output the version number
  -h, --help                                               display help for command

Commands:
  build [options] [siteDir]                                Build website.
  swizzle [options] [themeName] [componentName] [siteDir]  Wraps or ejects the original theme files into website folder for customization.
  deploy [options] [siteDir]                               Deploy website to GitHub pages.
  start [options] [siteDir]                                Start the development server.
  serve [options] [siteDir]                                Serve website locally.
  clear [siteDir]                                          Remove build artifacts.
  write-translations [options] [siteDir]                   Extract required translations of your site.
  write-heading-ids [options] [siteDir] [files...]         Generate heading ids in Markdown content.
  docs:version <version>                                   Tag a new docs version
  gen-api-docs [options] <id>                              Generates OpenAPI docs in MDX file format and sidebar.ts (if enabled).
  gen-api-docs:version [options] <id:version>              Generates versioned OpenAPI docs in MDX file format, versions.js and sidebar.ts (if enabled).
  clean-api-docs [options] <id>                            Clears the generated OpenAPI docs MDX files and sidebar.ts (if enabled).
  clean-api-docs:version [options] <id:version>            Clears the versioned, generated OpenAPI docs MDX files, versions.json and sidebar.ts (if enabled).

How to configure the plugin: https://docusaurus-openapi.tryingpan.dev/#configuring-the-plugin

[tjperry07]

@sserrata is there a reason why the package.json is not automatically updated when adding the plugin and theme?

[sserrata]

If you're referring to the scripts section in package.json, we don't update it because:

• Updating package.json scripts it not required/necessary to use the Docusaurus OpenAPI Docs plugin CLI
• Scripts tend to be highly opinionated and should be up to the maintainer to define

[tjperry07]

@notmatthewa Were you able to solve your install based on the convo above?

https://docusaurus-openapi.tryingpan.dev/#installation-existing-docusaurus-site

Get the most recent beta from here: https://www.npmjs.com/package/docusaurus-plugin-openapi-docs?activeTab=versions

1. Make sure you install the theme and the plugin.
2. Add them to your docusaurus.config. (Theme and plugin)

@sserrata I think the confusion a few of us are experiencing is how the instructions are formatted. I will make a PR, take it or leave it. But it might help so you won't have to answer this again, because I see it has come up a couple of times recently.

[notmatthewa]

@tjperry07 yes I was able to fix the issues. The main one is that some of my MDX files generate with an empty SchemaTabs element in them. This would cause the build to crash because a TabsList element requires at least one child TabItem.

I was able to fix this with a Python script that uses regex to remove the empty tags and runs after a gen-api-docs call.

Not sure if it's a bug I should report or an error in my setup but I can't find anything in my openapi.json that might cause it.

[tjperry07]

#786

[tjperry07]

Shout out to @sserrata for helping me through a PEBKAC error that I just could not see on my own.