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.
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-docswill 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:{ "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-docsfor 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.