Skip to content

Commit e3a0324

Browse files
mseong6251mseong6251
authored
Merge branch 'main' into mseong6251-patch-1
2 parents 5ebe8a0 + 47efb11 commit e3a0324

File tree

7 files changed

+953
-908
lines changed

7 files changed

+953
-908
lines changed

‎docs/reference/modules/ROOT/pages/configuration-reference.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1681,7 +1681,7 @@ A special step used to check out source code to the configured `path` (defaults
16811681
| `method`
16821682
| N
16831683
| String
1684-
| Checkout method. Valid options include `blobless` and `full`. (default: `full`)
1684+
| Checkout method. Valid options include `blobless` and `full`. (default: `blobless`)
16851685
16861686
| `path`
16871687
| N

‎gulp.d/tasks/build-api-docs.js‎

Lines changed: 78 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -102,22 +102,23 @@ function buildApiV1(callback) {
102102
/**
103103
* Build API v2 Documentation
104104
*
105-
* STRATEGY: Sophisticated pipeline matching original CircleCI build process
105+
* STRATEGY: Sophisticated pipeline for generating API documentation with code samples
106106
*
107107
* PIPELINE STEPS:
108108
* 1. Fetch live OpenAPI spec from CircleCI API
109-
* 2. Prepare spec (placeholder for future code sample enrichment)
110-
* 3. Apply JSON patches (customizations/corrections)
111-
* 4. Bundle and optimize (remove unused components)
109+
* 2. Bundle and resolve all $ref pointers (using Redocly)
110+
* 3. Generate code samples with httpsnippet (for cURL, Node.js, Python, Go, Ruby)
111+
* 4. Apply JSON patches - CURRENTLY DISABLED for simplicity
112112
* 5. Lint for quality assurance
113113
* 6. Generate final HTML with Redocly
114-
* 7. Cleanup temporary files
114+
* 7. Copy logo assets
115+
* 8. Cleanup temporary files
115116
*
116-
* WHY COMPLEX:
117+
* WHY THIS ORDER:
118+
* - Bundling first resolves $ref pointers, making parameters accessible
119+
* - Code samples need resolved parameters to generate valid snippets
120+
* - Linting catches issues before final HTML generation
117121
* - Live API ensures docs are always current
118-
* - Patches allow customization without modifying source
119-
* - Bundling optimizes file size and structure
120-
* - Linting catches issues before publication
121122
*/
122123
function buildApiV2(callback) {
123124
console.log('Building API v2 documentation with full pipeline...')
@@ -139,94 +140,88 @@ function buildApiV2(callback) {
139140
}
140141
console.log('✅ OpenAPI spec fetched')
141142

142-
// STEP 2: Prepare spec for processing
143-
// Add code samples using snippet-enricher-cli
144-
console.log('📝 Adding code samples to OpenAPI spec...')
145-
exec('cd build/temp-api-v2 && ../../node_modules/.bin/snippet-enricher-cli --targets="node_request,python_python3,go_native,shell_curl" --input=openapi.json > openapi-with-examples.json', (err, stdout, stderr) => {
143+
// STEP 2: Bundle, dereference, and optimize
144+
// --dereferenced: Resolves ALL $ref pointers so snippet generation can access definitions
145+
// --remove-unused-components: Removes unreferenced schemas to reduce file size
146+
console.log('📦 Bundling and dereferencing API spec...')
147+
exec('npx @redocly/cli bundle build/temp-api-v2/openapi.json --dereferenced --remove-unused-components --output build/temp-api-v2/openapi-bundled.json', (err, stdout, stderr) => {
146148
if (err) {
147-
console.error('❌ Failed to add code samples:', err)
148-
console.log('ℹ️ Falling back to unprocessed spec...')
149-
// Fallback: copy unprocessed file if snippet enricher fails
150-
fs.copyFileSync('build/temp-api-v2/openapi.json', 'build/temp-api-v2/openapi-with-examples.json')
151-
} else {
152-
console.log('✅ Code samples added to OpenAPI spec')
149+
console.error('❌ Failed to bundle API docs:', err)
150+
return callback(err)
153151
}
152+
console.log('✅ API docs bundled, dereferenced, and optimized')
153+
154+
// STEP 3: Add code samples using our custom script with Kong's httpsnippet
155+
// This runs AFTER bundling so all $ref pointers are resolved
156+
console.log('📝 Adding code samples to OpenAPI spec...')
157+
exec('node scripts/generate-api-snippets.js build/temp-api-v2/openapi-bundled.json build/temp-api-v2/openapi-with-examples.json', (err, stdout, stderr) => {
158+
if (err) {
159+
console.error('❌ Failed to add code samples:', err)
160+
if (stderr) console.error(stderr)
161+
console.log('ℹ️ Falling back to bundled spec without examples...')
162+
// Fallback: copy bundled file if snippet generation fails
163+
fs.copyFileSync('build/temp-api-v2/openapi-bundled.json', 'build/temp-api-v2/openapi-with-examples.json')
164+
} else {
165+
console.log('✅ Code samples added to OpenAPI spec')
166+
if (stdout) console.log(stdout)
167+
}
168+
169+
// STEP 4: Apply JSON patches (COMMENTED OUT - keeping simple for now)
170+
// Allows customizing the API spec without modifying the source
171+
// Uncomment this section when you need to apply custom patches
172+
// console.log('🔧 Applying JSON patches...')
173+
// applyJsonPatches(() => {
154174

155-
// STEP 3: Apply JSON patches
156-
// Allows customizing the API spec without modifying the source
157-
// Patches can fix errors, add descriptions, or customize for documentation
158-
console.log('🔧 Applying JSON patches...')
159-
applyJsonPatches(() => {
175+
// For now, skip patching and use the spec with examples as final
176+
console.log('ℹ️ Skipping JSON patches (disabled for simplicity)')
177+
fs.copyFileSync('build/temp-api-v2/openapi-with-examples.json', 'build/temp-api-v2/openapi-final.json')
160178

161-
// STEP 4: Bundle and remove unused components
162-
// Optimizes the spec by removing unreferenced schemas, reducing file size
163-
console.log('📦 Bundling API docs and removing unused components...')
164-
exec('npx @redocly/cli bundle build/temp-api-v2/openapi-patched.json --remove-unused-components --output build/temp-api-v2/openapi-final.json', (err, stdout, stderr) => {
179+
// STEP 5: Lint API docs
180+
// Quality check to catch issues before generating final docs
181+
console.log('🔍 Linting API docs...')
182+
exec('npx @redocly/cli lint build/temp-api-v2/openapi-final.json', (err, stdout, stderr) => {
165183
if (err) {
166-
console.error('❌ Failed to bundle API docs:', err)
167-
return callback(err)
184+
console.warn('⚠️ Linting warnings found, but continuing build...')
185+
console.log(stdout)
186+
} else {
187+
console.log('✅ API docs linting passed')
168188
}
169-
console.log('✅ API docs bundled')
170189

171-
// STEP 5: Lint API docs
172-
// Quality check to catch issues before generating final docs
173-
// Warnings don't stop the build, but errors would
174-
console.log('🔍 Linting API docs...')
175-
exec('npx @redocly/cli lint build/temp-api-v2/openapi-final.json', (err, stdout, stderr) => {
176-
if (err) {
177-
console.warn('⚠️ Linting warnings found, but continuing build...')
178-
console.log(stdout)
179-
} else {
180-
console.log('✅ API docs linting passed')
181-
}
190+
// STEP 6: Build final HTML documentation
191+
// Redocly transforms the OpenAPI spec into beautiful, interactive docs
192+
console.log('🏗️ Building docs with Redocly CLI...')
182193

183-
// STEP 6: Build final HTML documentation
184-
// Redocly transforms the OpenAPI spec into beautiful, interactive docs
185-
console.log('🏗️ Building docs with Redocly CLI...')
194+
const buildCommand = [
195+
'npx @redocly/cli build-docs build/temp-api-v2/openapi-final.json',
196+
'--output build/api/v2/index.html',
197+
'--config redocly.yaml',
198+
'--template custom-template.hbs',
199+
'--title "CircleCI API v2 Documentation"',
200+
'--disableGoogleFont=false',
201+
].join(' ')
186202

187-
// Build options for enhanced customization (all free options):
188-
// --title: Custom page title
189-
// --theme.openapi.disableSearch: Disable search (if needed)
190-
// --theme.openapi.hideDownloadButton: Hide download button
191-
// --template: Custom template (requires template file)
192-
// --options.maxDisplayedEnumValues: Limit enum display
203+
exec(buildCommand, (err, stdout, stderr) => {
204+
if (err) {
205+
console.error('❌ Failed to build API docs:', err)
206+
return callback(err)
207+
}
193208

194-
const buildCommand = [
195-
'npx @redocly/cli build-docs build/temp-api-v2/openapi-final.json',
196-
'--output build/api/v2/index.html',
197-
'--config redocly.yaml',
198-
'--template custom-template.hbs',
199-
'--title "CircleCI API v2 Documentation"',
200-
'--disableGoogleFont=false',
201-
// Additional options for free version:
202-
// '--theme.openapi.hideDownloadButton=true',
203-
// '--theme.openapi.disableSearch=true',
204-
// '--theme.openapi.nativeScrollbars=true'
205-
].join(' ')
209+
console.log('✅ API v2 docs built successfully')
206210

207-
exec(buildCommand, (err, stdout, stderr) => {
211+
// STEP 7: Copy logo file for template
212+
console.log('📋 Copying logo file...')
213+
exec('cp logo.svg build/api/v2/', (err) => {
208214
if (err) {
209-
console.error('❌ Failed to build API docs:', err)
210-
return callback(err)
215+
console.warn('⚠️ Warning: Could not copy logo file:', err.message)
216+
} else {
217+
console.log('✅ Logo file copied successfully')
211218
}
212219

213-
console.log('✅ API v2 docs built successfully')
214-
215-
// STEP 7: Copy logo file for template
216-
console.log('📋 Copying logo file...')
217-
exec('cp logo.svg build/api/v2/', (err) => {
218-
if (err) {
219-
console.warn('⚠️ Warning: Could not copy logo file:', err.message)
220-
} else {
221-
console.log('✅ Logo file copied successfully')
222-
}
223-
224-
// STEP 8: Cleanup temporary files
225-
// Remove intermediate files to keep build directory clean
226-
exec('rm -rf build/temp-api-v2', () => {
227-
console.log('🎉 API v2 documentation build completed!')
228-
callback()
229-
})
220+
// STEP 8: Cleanup temporary files
221+
// Remove intermediate files to keep build directory clean
222+
exec('rm -rf build/temp-api-v2', () => {
223+
console.log('🎉 API v2 documentation build completed!')
224+
callback()
230225
})
231226
})
232227
})

0 commit comments

Comments
 (0)