Render generated `swagger.json` for API documentation
- Dominant language
- TypeScript
- Stars
- 249
- Forks
- 176
- Avg merge
- 3d 8h
- Merged PRs (30d)
- 20
Description
**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](https://git-proxy.finos.org/docs/configuration/reference/) is autogenerated in `scripts/doc-schema.js`:
```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')
.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)
Contributor guide
Assessment
This issue has not been assessed yet.