Enable custom (user-specified) config file path

[jaeddy]

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:

const localConfig = {
  apiSpecPath: userConfig.apiSpecPath || '',
  docsRoot: userConfig.docsRoot || 'docs',
  redocRoot: userConfig.redocRoot || 'redoc-ui',
  redocTheme: userConfig.redocTheme || 'default',
  defaultBranch: userConfig.defaultBranch || 'master',
  branchPathBase: userConfig.branchPath || 'preview',
  contactUrl: userConfig.contactUrl || ''
};

Calling gh-openapi-docs will build the docs for a single OpenAPI spec (located at apiSpecPath). If you’re on master (or an alternative defaultBranch), 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:

{
  "apiSpecPath": "<path-to-apiA-spec>/openapi.yaml",
  "docsRoot": "docs/apiA"
}

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.:

gh-openapi-docs -c .apiA-spec-docs.json
gh-openapi-docs -c .apiB-spec-docs.json

We’d need to update the library (and CLI) to accept custom config file paths, but that shouldn’t be too hard.

[jb-adams]

+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

[tschaffter]

+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.
nlpsandbox/nlpsandbox-schemas#1

A good structure for organizing gh-pages files could be:

/docs/index.html
/openapi.json
/openapi.yaml
/develop/docs/index.thml
/develop/openapi.json
/develop/openapi.yaml
/1.0/docs/index.html
/1.0/openapi.json
/1.0/openapi.json

Alternative: nlpsandbox/nlpsandbox-schemas#1 (comment)

@jaeddy Keeping one configuration file may be better to prevent cluttering the root folder of the repo. We could add a parameter that accepts an array of path to openapi.yaml files.