Proposal: Markdown Generation, Types, UI/UX Overhaul #210

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.