OpenAPI3 to HTML documentation generator

[rishidev]

The Cloud WS, courtesy of @jaeddy, has been using a documentation builder that generates human readable specifications from OpenAPI documents. A number of groups would like to generate synchronized human and machine readable documentation. TASC could help ensure this can be adapted across Work Stream groups.

[mcupak]

Very cool - what's the tool the Cloud WS is using?

[jaeddy]

Thanks, @rishidev for opening this issue. @mcupak - the current tools being used by WES, DRS, and (I think) TRS and TES include:

• swagger2markup gradle plugin and asciidoctor to (1) automatically generate human-readable asciidoc files from the OpenAPI (swagger) yaml spec; and (2) incorporate
  manual content to build an overall document in HTML and PDF formats
• modified/simplified scripts from the Node.js package generator-openapi-repo to set up Swagger UI stuff for the repo
• other shell scripts and a bunch of custom Travis configuration to manage compiling/building assets as well as fetching/storing data in the right place on the gh-pages branch

You can find more details about the full setup in this PR.

The system is not especially stable, and requires a lot of unrelated (to the spec) dependencies to live in the repo. It also only works with OpenAPI/Swagger 2.0, due to limitations with swagger2markup.

I started working on a standalone package a few months ago that would be able to handle most of the tasks during the Travis build with only minor configuration. I've also started testing out a switch over to ReDoc, which would serve as a single tool to handle both the docs rendering provided by swagger2markup as well as the API demo UI provided by SwaggerUI. It also supports OpenAPI 3.0, which is a major plus. 🙂

Unfortunately, I haven't had much time to work on the package since October. I cleaned up a few items this week, so it's getting close to being functional. I'm also looping in @tschaffter from my team who has more Node.js experience than me (I have close to zero) to help out. Anyone else is welcome to take a look!

We're hoping to have an MVP wired up to one of the Cloud WS repos within the next week or so to unblock the migration of the spec from OpenAPI 2.0 to 3.0.

[jb-adams]

Hi @jaeddy, I'd be happy to help contribute to this. I think a general documentation builder that's available to all Work Streams and groups is the way to go.

[jaeddy]

Hey @jb-adams - that would be fantastic! You can find the relevant repo here:
https://github.com/ga4gh/gh-openapi-docs

The codebase is primarily Node.js (for which, as I mentioned, I'm a novice). I've created several issues based on what I think is needed — you're welcome to help tackle any of those! Please feel free to add new issues as well based on whatever you encounter.

If you have any higher level suggestions on design/structure, I'd love to hear your thoughts.

Many thanks in advance! 🙏

[rishidev]

This has now been updated, and applied to Cloud WS API suite. @jaeddy is there a homepage for the tool we can link to from here?

[susanfairley]

Adding a note following the TASC call this week that this somewhat relates to plans for the website and presenting documentation consistently. There could be an advantage to following up on this further after the website requirements are clear.