Is your feature request related to a problem? Please describe.
#1501, not yet merged as of creating this issue, refactors the endpoints to make them type-safe and documented. It generates a swagger.json (OpenAPI spec) that can be easily parsed into MDX and added to our website documentation.
Describe the solution you'd like
Automatically parse the generated swagger.json into MDX that's added to the website docs, similar to how the Schema Reference is autogenerated in scripts/doc-schema.js:
const { execFileSync } = require('child_process');
const { writeFileSync, readFileSync, mkdtempSync } = require('fs');
const { tmpdir } = require('os');
const { sep } = require('path');
const JSFH_CONFIG = './jsfh.config.json';
const SCHEMA_FILE = './config.schema.json';
const OUTPUT_PATH = './website/docs/configuration/reference.mdx';
try {
const osTempdir = tmpdir();
const tempdir = mkdtempSync(`${osTempdir}${sep}`);
const genDocOutput = execFileSync('generate-schema-doc', [
'--config-file',
JSFH_CONFIG,
SCHEMA_FILE,
`${tempdir}${sep}schema.md`,
]).toString('utf-8');
console.log(genDocOutput);
const schemaDoc = readFileSync(`${tempdir}${sep}schema.md`, 'utf-8')
.replace(/\s\s\n\n<\/summary>/g, '\n</summary>')
.replace(/# GitProxy configuration file/g, '# Schema Reference'); // https://github.com/finos/git-proxy/pull/327#discussion_r1377343213
const docString = `---
title: Schema Reference
description: JSON schema reference documentation for GitProxy
---
${schemaDoc}
`;
writeFileSync(OUTPUT_PATH, docString);
console.log(`Wrote schema reference to ${OUTPUT_PATH}`);
} catch (err) {
console.error(err);
}
Describe alternatives you've considered
An alternative is to use Swagger UI which is feature rich, allows testing endpoints, etc., although this would add a runtime dependency.
Additional context
Original issue: #1343 (Closed since the requirements have changed considerably since we needed to first improve the API code and docstrings)
Is your feature request related to a problem? Please describe.
#1501, not yet merged as of creating this issue, refactors the endpoints to make them type-safe and documented. It generates a
swagger.json(OpenAPI spec) that can be easily parsed into MDX and added to our website documentation.Describe the solution you'd like
Automatically parse the generated
swagger.jsoninto MDX that's added to the website docs, similar to how the Schema Reference is autogenerated inscripts/doc-schema.js:Describe alternatives you've considered
An alternative is to use Swagger UI which is feature rich, allows testing endpoints, etc., although this would add a runtime dependency.
Additional context
Original issue: #1343 (Closed since the requirements have changed considerably since we needed to first improve the API code and docstrings)