OpenAPI or Swagger for REST APIs [Proposal]

[cameronelliott]

I want to say, I love how Docusaurus easily enables creation of sites & documentation at the same time. Nice job.

I am writing regarding a question or possible enhancement.
Are there any suggestions on how to use Docusaurus to document simple REST APIs ?

Obviously I can document by my API in markdown by hand, but I am wondering what the next level of efficiency would be where I have evolving APIs, without re-updating my Docusaurus markdown by hand after each change to my API specification.

The Slate project has a number of 3rd party tools to convert from Swagger specs to Slate-markdown, maybe one thing I could explore is creating or adjusting a tool to perform the same function for Docusaurus.
link: OpenAPI to Slate-markdown

Any suggestions on how to best use Docusaurus in this manner?, or how how I might tweak or improve Docusaurus for documenting smaller REST APIs? All suggestions appreciated. Including, don't do this! :)

[JoelMarcey]

@Cameron-elliott Hi Cameron! Thanks for bringing this up. API support in the core of Docusaurus is something that we have thought about but have not implemented for v1. I should probably create a feature request issue if I haven't already.

You are correct, markdown is one way to do this. You could create a script that updates your markdown automatically.

The other way is to use the static HTML output by some tools like doxygen, Swagger via codegen, etc. And the use that static HTML directly in Docusaurus. FastText does this for example: https://fasttext.cc/docs/en/api.html. You can see: https://docusaurus.io/docs/en/custom-pages.html#adding-static-pages

That said, having something in the core that would allow for an npm command to generate API docs from common systems would be interesting. I think having a nice plugin module may be the best way to go there.

[willvincent]

We've been using redoc (outside of docusaurus) to display our api docs. I've been pretty happy with it. Rather than reinventing the wheel, you could just make that available to parse openapi/swagger format json files.

[JoelMarcey]

@willvincent That is definitely a reasonable idea. The question I have been struggling with is which tools to support. Once you add support for one, you will get asked to support a lot more. Maybe that is ok. Start with one or two. That's why I think being able to plugin various tools or formats would be optimal. We can provide a couple for reference and then show how others could be incorporated.

[willvincent]

A plugin system would be handy for such things.

[RemyLespagnol]

+1

[cameronelliott]

Just curious, has the core Docusaurus team had any discussions oh this topic that would help people still pondering this? Or maybe someone has seen how others have done this, and wouldn't mind sharing that approach here? Thanks for any thoughts.

[endiliey]

Just giving some thought. On the next major version, we have a plugin system that basically let you pull any data sources.

See #1438 for an overview of plugins/themes/presets API.

[xp4ck]

Just wondering if there is any progress? Maybe somebody works on creating a plugin for integrating OpenAPI schemas:) ?

[ShrijanaCodes]

Hi, is there any update to this proposal? Are there any resources on best practices for documenting APIs using Docusaurus?

[henricook]

This is basically the reason we didn't choose docusaurus. Progress on this would be great, we loved everything else.

[JoelMarcey]

@yangshun Do you know if there has been any work on this for v2, even if just planning? Thanks.

[yangshun]

@JoelMarcey not planned. It's unlikely we'll pursue this effort as FB Docusaurus sites don't use it. We made v2 as a platform so that the community can support features on their own. Even if we were to build this, we don't use it for our own sites and maintainability will be an issue. This is better left up to community members who need to use it and can maintain it.

[bourdakos1]

I've started working on an OpenAPI Docusaurus plugin. It's still a work in progress, but this is what it looks like:

[willvincent]

@bourdakos1 how usable is it in it's current state?

Looks like it's not just a plugin in the linked repo..

[bourdakos1]

@willvincent it should be pretty usable minus some bugs here and there. I've only been working on the plugin for a couple days, should be pretty stable by the end of the week.

[bourdakos1]

@willvincent I haven't pushed the plugin to npm yet, so you would need to copy the docusaurus-plugin-openapi folder into your project and then add the following to your docusaurus.config.js:

plugins: [
    [path.resolve(__dirname, "./docusaurus-plugin-openapi"), {
      openapiPath: require.resolve('./openapi.json')
    }],
  ],

(You'd also need to build it)

[bourdakos1]

It's on npm now so just:

yarn add docusaurus-plugin-openapi

update docusaurus.config.js:

plugins: [
  ["docusaurus-plugin-openapi", {
    openapiPath: require.resolve("./openapi.json"),
  }],
],

and maybe add a link themeConfig.navbar.links:

{
  to: "api/",
  activeBasePath: "api",
  label: "API",
  position: "left",
}

[slorber]

Hey, that looks great.

Wondering: why not integrating open-api as an iframe of a D2 website? I've not used it for a long time now but isn't there some kind of client UI already provided (SwaggerUI or something like that?).

A basic integration could be to add this UI as an iframe in an existing page, or even embedded into a MDX document.

This deeper integration via plugin would need to rebuild each time there's a change to your api file, unlike the iframe solution. Isn't that a problem?

[bourdakos1]

@slorber Thanks :)

I’m personally not a huge fan of SwaggerUI, I’d rather have something that look and feels more native to the rest of the docs.

With the way the plugin is set up now it would need to rebuild whenever you change the api file. This doesn’t really affect me, because I redeploy my docs when I make updates to my services. I think building it also has the benefits of the pages being more static.

However, I can see how it would be useful to be able to point Docusaurus to a link to your openapi spec and be able to adapt whenever it changes. I think this is still possible as a plugin (make the openapi component browser only and fetch the spec dynamically) you would just lose the benefit of the pages being prerendered

[rohit-gohri]

With v2 it is really easy to use redoc since we can use any react components in it. Problem comes in theming it correctly. It works pretty great with normal theme, but the styles conflict in dark mode and text becomes unreadable.

Edit: Have been working on a dark theme for redoc, will try to publish it

[slorber]

great to know, thanks :)

If this is a problem it's possible to just disable the dark mode for now :)

@bourdakos1 your solution works, but you are doing it the hard way (I mean, duplicating the docs plugin code).
Do you really need all the features of docs, with the sidebar, custom paths per api etc?
One solution is to just plug some React components in a JSX page and render the openapi stuff dynamically.

There may be value in having a hierarchy of routes for the apis, and organize them, but there's probably little value in doing SSR rendering for dynamic api widgets.

[bourdakos1]

@slorber I definitely want a sidebar, but don't really need custom paths. I started out by doing it with only one api page and hash routing for all the sections, but switched to actual routes for no real reason 🤷‍♂️

[rohit-gohri]

I published a simple gist with a Redocusaurus component with redoc theme options included to match Docusaurus styling (including dark mode) : https://gist.github.com/rohit-gohri/b1a19f37702cfe4a6c5a47933a11785b

EDIT: Published a plugin from it: redocusaurus.

[slorber]

Thanks @rohit-gohri that looks nice

If you want some help to publish this as a plugin tell me.

[ymolists]

@bourdakos1 . Thats amazing !

I have multiple projects each with one openapi spec. It seems its meant to have only one spec ? I can open an issue on the repo if you think this is something you are going to support.

[bourdakos1]

@ymolists thanks 😁 feel free to open an issue, Ill take a look and see how hard it will be to add

[devdudeio]

damn we really need something like this. any ETA for this feature?

[slorber]

@dude-awesome it's not planned that core Docusaurus contributors work on this.
We are a small team and should concentrate on core features, and let the community tackle specific needs in plugins.
We can't maintain all Docusaurus plugins ourselves.
If plugin authors are blocked to implement such features, we'll do our best to unlock them.

[ArtFlag]

Just found this implementation that does the same thing, without the scrolling issue and uses a plugin.

Sébastien, maybe it might be worth a shot to contact the creator?

[slorber]

Thanks for this interesting article. The creator is @davidjgoss so let's just ping him here 😅

I don't have time to do it right now but I think adding some kind of "recipes" section to our doc with the most frequent how-to questions would be nice.

[davidjgoss]

Hi @ArtFlag @slorber!

I'm happy to wrap this up and publish as a plugin if people will find it useful.

[slorber]

It would be nice to have a plugin for that thanks.

[rohit-gohri]

I have made a preset, redocusaurus, from the gist. Can use it like:

// docusaurus.config.js

module.exports = {
  // ...
  presets: [
    [
      'redocusaurus',
      {
        specs: [{
          routePath: '/api/'
          specUrl: 'https://redocly.github.io/redoc/openapi.yaml',
        }],
      }
    ],
  ],
  // ...
};

It includes a theme docusaurus-theme-redoc with the Redoc component and styling changes, and a plugin to create pages from OpenAPI yaml files or links, docusaurus-plugin-redoc.

Read more here: https://github.com/rohit-gohri/redocusaurus/
Demo here: https://rohit-gohri.github.io/redocusaurus/

The docs are a little WIP, if anything is missing please open an issue.

[davidjgoss]

Thanks for doing that @rohit-gohri - looks great! I've added an update to my post.

[Josh-Cena]

There are already plugins like redocusaurus or plugin-openapi that do this.