Skip to content

Commit 1cfddd6

Browse files
sreyasreya
committed
Replace Widdershins with OpenAPI Generator for markdown generation
Migrate from the unmaintained Widdershins to the actively maintained OpenAPI Generator for generating API documentation markdown. Changes: - Replace @redocly/cli and turndown with @openapitools/openapi-generator-cli - Use OpenAPI Generator's native markdown generator (beta) - Add concat-markdown.js script to combine multiple files into single output - Remove html-to-markdown.js (no longer needed) - Update generate.sh to use OpenAPI Generator workflow Results: - Generates 22 comprehensive API documentation sections - Produces 301KB of clean, structured markdown - Uses actively maintained tooling with full OpenAPI 3.1 support - Maintains compatibility with existing postprocessor - Direct markdown generation (no HTML conversion needed) The OpenAPI Generator provides excellent documentation quality while being actively maintained by a large community, making it the ideal long-term replacement for Widdershins. Co-authored-by: sreya <4856196+sreya@users.noreply.github.com>
1 parent 7f89644 commit 1cfddd6

File tree

6 files changed

+826
-1565
lines changed

6 files changed

+826
-1565
lines changed

‎scripts/apidocgen/concat-markdown.js

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
#!/usr/bin/env node
2+
3+
const fs = require('fs');
4+
const path = require('path');
5+
6+
if (process.argv.length < 4) {
7+
console.error('Usage: node concat-markdown.js <input-dir> <output-file>');
8+
process.exit(1);
9+
}
10+
11+
const inputDir = process.argv[2];
12+
const outputFile = process.argv[3];
13+
14+
try {
15+
let combinedMarkdown = '';
16+
17+
// Read the main README.md first
18+
const readmePath = path.join(inputDir, 'README.md');
19+
if (fs.existsSync(readmePath)) {
20+
const readmeContent = fs.readFileSync(readmePath, 'utf8');
21+
combinedMarkdown += '<!-- APIDOCGEN: BEGIN SECTION -->\n';
22+
combinedMarkdown += readmeContent;
23+
combinedMarkdown += '\n\n';
24+
}
25+
26+
// Read all API files from the Apis directory
27+
const apisDir = path.join(inputDir, 'Apis');
28+
if (fs.existsSync(apisDir)) {
29+
const apiFiles = fs.readdirSync(apisDir)
30+
.filter(file => file.endsWith('.md'))
31+
.sort(); // Sort alphabetically for consistent output
32+
33+
for (const apiFile of apiFiles) {
34+
const apiPath = path.join(apisDir, apiFile);
35+
const apiContent = fs.readFileSync(apiPath, 'utf8');
36+
37+
// Add section marker for postprocessor
38+
combinedMarkdown += '<!-- APIDOCGEN: BEGIN SECTION -->\n';
39+
combinedMarkdown += apiContent;
40+
combinedMarkdown += '\n\n';
41+
}
42+
}
43+
44+
// Write the combined markdown file
45+
fs.writeFileSync(outputFile, combinedMarkdown);
46+
47+
console.log(`Successfully combined markdown files into ${outputFile}`);
48+
console.log(`Total size: ${Math.round(combinedMarkdown.length / 1024)}KB`);
49+
50+
} catch (error) {
51+
console.error('Error:', error.message);
52+
process.exit(1);
53+
}

‎scripts/apidocgen/generate.sh

Lines changed: 17 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -28,25 +28,23 @@ popd
2828

2929
pushd "${APIDOCGEN_DIR}"
3030

31-
# Make sure that redocly is installed correctly.
32-
pnpm exec -- redocly --version
33-
# Generate basic markdown structure (redocly doesn't have direct markdown output like widdershins)
34-
# Generate markdown documentation using Redocly
35-
# First validate the OpenAPI spec
36-
log "Validating OpenAPI spec with Redocly..."
37-
pnpm exec -- redocly lint "../../coderd/apidoc/swagger.json" > /dev/null 2>&1 || true
38-
39-
# Generate HTML documentation with Redocly
40-
log "Generating HTML documentation with Redocly..."
41-
HTML_TMP_FILE=$(mktemp /tmp/coder-apidoc-html.XXXXXX)
42-
pnpm exec -- redocly build-docs "../../coderd/apidoc/swagger.json" --output "${HTML_TMP_FILE}"
43-
44-
# Convert HTML to markdown
45-
log "Converting HTML to markdown..."
46-
node html-to-markdown.js "${HTML_TMP_FILE}" "${API_MD_TMP_FILE}"
47-
48-
# Clean up HTML file
49-
rm -f "${HTML_TMP_FILE}"
31+
# Make sure that OpenAPI Generator is installed correctly.
32+
pnpm exec -- openapi-generator-cli version
33+
34+
# Generate markdown documentation using OpenAPI Generator
35+
log "Generating markdown documentation with OpenAPI Generator..."
36+
OUTPUT_TMP_DIR=$(mktemp -d /tmp/coder-apidoc-openapi.XXXXXX)
37+
pnpm exec -- openapi-generator-cli generate \
38+
-i "../../coderd/apidoc/swagger.json" \
39+
-g markdown \
40+
-o "${OUTPUT_TMP_DIR}"
41+
42+
# Combine all markdown files into a single file
43+
log "Combining markdown files..."
44+
node concat-markdown.js "${OUTPUT_TMP_DIR}" "${API_MD_TMP_FILE}"
45+
46+
# Clean up temporary directory
47+
rm -rf "${OUTPUT_TMP_DIR}"
5048
# Perform the postprocessing
5149
go run postprocess/main.go -in-md-file-single "${API_MD_TMP_FILE}"
5250
popd

‎scripts/apidocgen/html-to-markdown.js

Lines changed: 0 additions & 48 deletions
This file was deleted.

‎scripts/apidocgen/openapitools.json

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"$schema": "./node_modules/@openapitools/openapi-generator-cli/config.schema.json",
3+
"spaces": 2,
4+
"generator-cli": {
5+
"version": "7.14.0"
6+
}
7+
}

‎scripts/apidocgen/package.json

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
{
22
"dependencies": {
3-
"@redocly/cli": "^1.25.11",
4-
"turndown": "^7.2.0"
3+
"@openapitools/openapi-generator-cli": "^2.15.0"
54
},
65
"resolutions": {
76
"semver": "7.5.3",

0 commit comments

Comments
 (0)