Skip to content

Render generated swagger.json for API documentation #1510

@jescalada

Description

@jescalada

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)

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions