finos / finos/git-proxy

Render generated `swagger.json` for API documentation

Open
#1,510 0 comments 0 reactions 1 assignee Claimed by @fabiovincenzi View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.