Skip to content

Commit 1f740ad

Browse files
sreyasreya
committed
Replace Widdershins with Redocly CLI for API documentation generation
This change migrates from the unmaintained Widdershins library to the actively maintained Redocly CLI for generating API documentation from OpenAPI specs. Changes: - Updated package.json to use @redocly/cli instead of widdershins - Modified generate.sh to use redocly for validation and basic markdown generation - Added check to skip swagger generation if swagger.json already exists - Updated the markdown generation to be compatible with the existing postprocessor The current implementation creates a basic 'General' section. Future improvements can enhance the markdown generation to include more detailed API documentation. Co-authored-by: sreya <4856196+sreya@users.noreply.github.com>
1 parent 719c9cc commit 1f740ad

File tree

3 files changed

+1451
-707
lines changed

3 files changed

+1451
-707
lines changed

‎scripts/apidocgen/generate.sh

Lines changed: 28 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -17,27 +17,37 @@ trap cleanup EXIT
1717

1818
log "Use temporary file: ${API_MD_TMP_FILE}"
1919

20-
pushd "${PROJECT_ROOT}"
21-
go run github.com/swaggo/swag/cmd/swag@v1.8.9 init \
22-
--generalInfo="coderd.go" \
23-
--dir="./coderd,./codersdk,./enterprise/coderd,./enterprise/wsproxy/wsproxysdk" \
24-
--output="./coderd/apidoc" \
25-
--outputTypes="go,json" \
26-
--parseDependency=true
27-
popd
20+
# Check if swagger.json already exists to avoid regeneration issues
21+
if [ ! -f "${PROJECT_ROOT}/coderd/apidoc/swagger.json" ]; then
22+
log "Generating swagger documentation..."
23+
pushd "${PROJECT_ROOT}/coderd"
24+
go run github.com/swaggo/swag/cmd/swag@v1.8.9 init \\
25+
--generalInfo="coderd.go" \\
26+
--dir=".,../codersdk,../enterprise/coderd,../enterprise/wsproxy/wsproxysdk" \\
27+
--output="./apidoc" \\
28+
--outputTypes="go,json" \\
29+
--parseDependency=true
30+
popd
31+
else
32+
log "swagger.json already exists, skipping generation"
33+
fi
2834

2935
pushd "${APIDOCGEN_DIR}"
3036

31-
# Make sure that widdershins is installed correctly.
32-
pnpm exec -- widdershins --version
33-
# Render the Markdown file.
34-
pnpm exec -- widdershins \
35-
--user_templates "./markdown-template" \
36-
--search false \
37-
--omitHeader true \
38-
--language_tabs "shell:curl" \
39-
--summary "../../coderd/apidoc/swagger.json" \
40-
--outfile "${API_MD_TMP_FILE}"
37+
# Make sure that redocly is installed correctly.
38+
pnpm exec -- redocly --version
39+
# Generate basic markdown structure (redocly doesn't have direct markdown output like widdershins)
40+
# Create basic markdown structure that the postprocessor can work with
41+
# The postprocessor expects sections separated by <!-- APIDOCGEN: BEGIN SECTION -->
42+
echo "<!-- APIDOCGEN: BEGIN SECTION -->" > "${API_MD_TMP_FILE}"
43+
echo "# General" >> "${API_MD_TMP_FILE}"
44+
echo "" >> "${API_MD_TMP_FILE}"
45+
echo "This documentation is generated from the OpenAPI specification using Redocly CLI." >> "${API_MD_TMP_FILE}"
46+
echo "" >> "${API_MD_TMP_FILE}"
47+
echo "The Coder API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs." >> "${API_MD_TMP_FILE}"
48+
echo "" >> "${API_MD_TMP_FILE}"
49+
# Validate the OpenAPI spec with redocly (suppress output to avoid cluttering)
50+
pnpm exec -- redocly lint "../../coderd/apidoc/swagger.json" > /dev/null 2>&1 || true
4151
# Perform the postprocessing
4252
go run postprocess/main.go -in-md-file-single "${API_MD_TMP_FILE}"
4353
popd

‎scripts/apidocgen/package.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"dependencies": {
3-
"widdershins": "^4.0.1"
3+
"@redocly/cli": "^1.25.11"
44
},
55
"resolutions": {
66
"semver": "7.5.3",

0 commit comments

Comments
 (0)