Proposal: Markdown Generation, Types, UI/UX Overhaul

I have a couple different changes I think could benefit this project. Let me know if you would be open to these changes and I’d be happy to do the work of submitting PRs around them.

1. Refactor markdown generation to JSX

Currently the generation of markdown is handled through a custom utility defined in docusaurus-plugin-openapi. The implementation uses these to generate the independent sections, such as: createParamsTable, createStatusCodesTable, etc.

I’d like to propose refactoring these to render with React directly, to eliminate the declarative pattern of:

create("thead", {
  children: create("tr", {
    children: create("th", {
      style: { textAlign: "left" },
      children: `${
        type.charAt(0).toUpperCase() + type.slice(1)
      } Parameters`,
    }),
  }),
}),

and moving to:

return (
  <thead>
    <tr>
      <th style={textAlign: 'left' }>
        {type.chartAt(0).toUpperCase() + type.slice(1)} Parameters
      </th>
    </tr>
  </thead>
);

When docusaurus builds, the SSR behavior will still output the contents as HTML.

The benefits here are:

1. Removes internal utils for DOM creation
2. Standardizes on HTML/JSX
3. Allows for more complex UI implementations that the existing utilities would not easily satisfy

2. Move markdown sections to docusaurus-theme-openapi

By moving the markdown section components (params table, status table, etc.) to the theme and exporting from that library, developers can more easily build custom ApiItem/ApiPage implementations, while reusing more of the internal sections.

For example, in my project I have a custom apiItemComponent defined & then need to manage recreating the UI if I want to customize the ApiContent section. Ideally I could reference all the existing sections and render a custom implementation for a specific section (e.g.: createStatusCodesTable).

3. Expose OpenAPI types

Continuing on the 2nd point, I would like to expose the OpenAPI types declared here: https://github.com/cloud-annotations/docusaurus-openapi/blob/main/packages/docusaurus-plugin-openapi/src/types.ts to the entry point of the module. This would allow custom implementations that are building custom section replacements, to leverage the existing types.

4. UI/UX Overhaul

I am unsure if the current design is based off any thing specific. The project that I am migrating to docusaurus currently is hosted in Readme.io. Their UI design has some nice improvements that I think would enhance this plugin: https://sample-threes.readme.io/reference/authentication-1

If approved, I would like to merge this work into a “next” branch, and split up the individual migrations. We wouldn’t need to match the design 1:1, but there are a few immediate differences that I think would benefit this project:

• Color coded request methods & combining the request method and server url into a single area

• Move the inputs for path params/request body in the same area as their API description (also clicking the path parameter focuses the input)

• Click a response opens a dialog with the shape of the response:

• Users can click predefined response examples

• The language options can handle many options, without clipping off the screen.

[bourdakos1]

A little background, when we first wrote this we used JSX to render everything. However, we ran into a handful of issues with the approach. The way we had it working was to save each piece of openapi content that could be formatted with markdown as a markdown file that Docusaurus would ingest, but this didn’t scale very well, it was a lot of piping and a lot of files generated. What we do now is basically turn a page of the spec into a single markdown file, that’s what the “ApiContent” component is. This approach has been working pretty well so far and has the added benefit of the generated markdown being reusable outside of Docusaurus.

I’ll dig around and see if there were any other big reasons for why we switched to this new markdown generation approach.

I’m happy to switch back to JSX, but I’d like to hear more about your plan first

[sean-perkins]

That would be awesome, thanks @arrigolupori. I should have a few PRs up by this weekend to tackle the higher level UI refactors. I am going to leave the form control UI alone at first, but will migrate that once the new main container UI is in place.

One thing that I am unaware of how to best solve for, is when moving the rendering into JSX, we lose the ability of rendering the OpenAPI spec information that contains markdown formatted contents. My first PRs will avoid this scenario, as I will still be rendering the <ApiContent /> component: https://github.com/cloud-annotations/docusaurus-openapi/blob/e5c0ec7fafda112cc3c4c297a4ae36e85f8e3552/packages/docusaurus-theme-openapi/src/theme/ApiItem/index.tsx#L38 for most of the sections, but if anyone has ideas let me know 👍

For example, if my OpenAPI endpoint description was:

  description: "This is a description. :::tip Try it out ::: **This should be bolded**"

We want to continue to render that output as formatted markdown & admonitions. We could pass the contents through a plugin like react markdown again, but this will only format standard markdown into HTML. I would assume there is a docusaurus utility or internal function that helps solve for this.

I am unsure why the <ApiContent /> approach does not have this problem and renders the markdown correctly.