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

No one assigned

    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