Open jaeddy opened 3 years ago
+1 for supporting this feature. It would allow the GA4GH OpenAPI specs in the hts-specs repo (ie. refget and htsget) to be built by this tool
+1 This feature would also be useful for my repo https://github.com/data2health/nlp-sandbox-schemas where I list several APIs:
This ticket contains some notes I took regarding the organization/location of the files to host on gh-pages
.
https://github.com/data2health/nlp-sandbox-schemas/issues/1
A good structure for organizing gh-pages
files could be:
This idea would allow a user to handle multiple API specs in the same repo…
The default config file (i.e.,
.spec-docs.json
) includes the following options:Calling
gh-openapi-docs
will build the docs for a single OpenAPI spec (located atapiSpecPath
). If you’re onmaster
(or an alternativedefaultBranch
), then the docs will be stored under<repo>/docs/
; if you’re on any other branch, they’ll live under<repo>/preview/<branch-name>/docs
.I believe a repo maintainer could set up multiple config files, one for each API — e.g.,
.apiA-spec-docs.json
,.apiB-spec-docs.json
— and customize the following fields in each:So, like above, if you’re on
master
, the docs for apiA would be created/stored at<repo>/docs/apiA
; on any other branch, they’ll be at<repo>/preview/<branch-name>/docs/apiA
(the user could decide whether a different hierarchy is preferable).In the GH Action or TravisCI script, you would just need to call
gh-openapi-docs
for each API/config — i.e.:We’d need to update the library (and CLI) to accept custom config file paths, but that shouldn’t be too hard.