From 60331dfdcd576e85d91ec4bacf5af4d45d0dd4d7 Mon Sep 17 00:00:00 2001 From: Iurii Golovinskii Date: Wed, 13 Aug 2025 05:27:02 +0300 Subject: [PATCH 1/7] fix:[FE] The index.html file is missing during export document --- src/apitypes/rest/rest.document.ts | 2 -- src/strategies/export-rest-operations-group.strategy.ts | 3 +-- src/strategies/export-version.strategy.ts | 7 +++---- 3 files changed, 4 insertions(+), 8 deletions(-) diff --git a/src/apitypes/rest/rest.document.ts b/src/apitypes/rest/rest.document.ts index 14732ca..97b10cd 100644 --- a/src/apitypes/rest/rest.document.ts +++ b/src/apitypes/rest/rest.document.ts @@ -125,7 +125,6 @@ export async function createRestExportDocument( templateResolver: _TemplateResolver, allowedOasExtensions?: OpenApiExtensionKey[], generatedHtmlExportDocuments?: ExportDocument[], - addBackLink?: boolean, ): Promise { const exportFilename = `${getDocumentTitle(filename)}.${format}` const [[document], blobProperties] = dump(removeOasExtensions(JSON.parse(data), allowedOasExtensions), EXPORT_FORMAT_TO_FILE_FORMAT.get(format)!) @@ -138,7 +137,6 @@ export async function createRestExportDocument( packageName, version, templateResolver, - addBackLink, ), filename: exportFilename, } diff --git a/src/strategies/export-rest-operations-group.strategy.ts b/src/strategies/export-rest-operations-group.strategy.ts index aaae9f6..a1a6977 100644 --- a/src/strategies/export-rest-operations-group.strategy.ts +++ b/src/strategies/export-rest-operations-group.strategy.ts @@ -100,9 +100,8 @@ async function exportReducedDocuments(config: ExportRestOperationsGroupBuildConf }, buildResult, contexts) const generatedHtmlExportDocuments: ExportDocument[] = [] - const restDocuments = [...buildResult.documents.values()].filter(isRestDocument) const transformedDocuments = await Promise.all([...buildResult.documents.values()].map(async document => { - return createRestExportDocument?.(document.filename, JSON.stringify(document.data), format, packageName, version, templateResolver, allowedOasExtensions, generatedHtmlExportDocuments, restDocuments.length > 1) + return createRestExportDocument?.(document.filename, JSON.stringify(document.data), format, packageName, version, templateResolver, allowedOasExtensions, generatedHtmlExportDocuments) })) buildResult.exportDocuments.push(...transformedDocuments) diff --git a/src/strategies/export-version.strategy.ts b/src/strategies/export-version.strategy.ts index 5e3759c..8a6eb2d 100644 --- a/src/strategies/export-version.strategy.ts +++ b/src/strategies/export-version.strategy.ts @@ -76,10 +76,9 @@ async function exportToHTML(config: ExportVersionBuildConfig, buildResult: Build if (generatedHtmlExportDocuments.length > 0) { buildResult.exportDocuments.push(...await createCommonStaticExportDocuments(packageName, version, templateResolver, shouldAddIndexPage ? 'index.html' : buildResult.exportDocuments[0].filename)) } - if (shouldAddIndexPage) { - const readme = await buildResult.exportDocuments.find(({ filename }) => filename.toLowerCase() === 'readme.md')?.data.text() - buildResult.exportDocuments.push(createUnknownExportDocument('index.html', await generateIndexHtmlPage(packageName, version, generatedHtmlExportDocuments, templateResolver, readme))) - } + + const readme = await buildResult.exportDocuments.find(({ filename }) => filename.toLowerCase() === 'readme.md')?.data.text() + buildResult.exportDocuments.push(createUnknownExportDocument('index.html', await generateIndexHtmlPage(packageName, version, generatedHtmlExportDocuments, templateResolver, readme))) } async function defaultExport(config: ExportVersionBuildConfig, buildResult: BuildResult, contexts: BuildTypeContexts): Promise { From 08bf777cb238fc46491e16e00ec53717b1dcd9b4 Mon Sep 17 00:00:00 2001 From: Iurii Golovinskii Date: Wed, 13 Aug 2025 05:37:59 +0300 Subject: [PATCH 2/7] fixed tests --- src/utils/export.ts | 4 ++-- test/export.test.ts | 3 ++- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/src/utils/export.ts b/src/utils/export.ts index 8b80573..fa0512b 100644 --- a/src/utils/export.ts +++ b/src/utils/export.ts @@ -39,10 +39,10 @@ export async function generateLegalStatementPage(packageName: string, version: s return new Blob([filled]) } -export async function generateHtmlPage(document: string, fileTitle: string, packageName: string, version: string, templateResolver: _TemplateResolver, addBackLink: boolean = false): Promise { +export async function generateHtmlPage(document: string, fileTitle: string, packageName: string, version: string, templateResolver: _TemplateResolver): Promise { const template = await (await templateResolver('page.html')).text() const apispecViewScript = await (await templateResolver('scripts/apispec-view.js')).text() - const breadcrumbs = addBackLink ? `
Table of contents > ${fileTitle}
` : '' + const breadcrumbs = `
Table of contents > ${fileTitle}
` const filled = template .replace('{{fileTitle}}', fileTitle) // arrow function disables replacement patterns like $& diff --git a/test/export.test.ts b/test/export.test.ts index 9798d89..a9c368f 100644 --- a/test/export.test.ts +++ b/test/export.test.ts @@ -211,7 +211,7 @@ describe('Export test', () => { expect(result.exportFileName).toEqual('export_single-document-version.zip') expect(result).toEqual(exportDocumentsMatcher([ exportDocumentMatcher('1.html'), - + exportDocumentMatcher('index.html'), exportDocumentMatcher('ls.html'), exportDocumentMatcher('resources/corporatelogo.png'), exportDocumentMatcher('resources/styles.css'), @@ -268,6 +268,7 @@ describe('Export test', () => { }) expect(result.exportFileName).toEqual('export_no-documents-version.zip') expect(result).toEqual(exportDocumentsMatcher([ + exportDocumentMatcher('index.html'), exportDocumentMatcher('Document.docx'), exportDocumentMatcher('README.md'), exportDocumentMatcher('Test.png'), From 7a7648aa7181ed3ae6ab84e061abff6563f5df32 Mon Sep 17 00:00:00 2001 From: Iurii Golovinskii Date: Wed, 13 Aug 2025 07:35:01 +0300 Subject: [PATCH 3/7] fixed bug --- src/strategies/export-rest-operations-group.strategy.ts | 4 +--- test/export.test.ts | 2 +- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/src/strategies/export-rest-operations-group.strategy.ts b/src/strategies/export-rest-operations-group.strategy.ts index a1a6977..3a84f24 100644 --- a/src/strategies/export-rest-operations-group.strategy.ts +++ b/src/strategies/export-rest-operations-group.strategy.ts @@ -110,8 +110,6 @@ async function exportReducedDocuments(config: ExportRestOperationsGroupBuildConf const shouldAddIndexPage = generatedHtmlExportDocuments.length > 1 buildResult.exportDocuments.push(...await createCommonStaticExportDocuments(packageName, version, templateResolver, shouldAddIndexPage ? 'index.html' : buildResult.exportDocuments[0].filename)) - if (shouldAddIndexPage) { - buildResult.exportDocuments.push(createUnknownExportDocument('index.html', await generateIndexHtmlPage(packageName, version, generatedHtmlExportDocuments, templateResolver))) - } + buildResult.exportDocuments.push(createUnknownExportDocument('index.html', await generateIndexHtmlPage(packageName, version, generatedHtmlExportDocuments, templateResolver))) } } diff --git a/test/export.test.ts b/test/export.test.ts index a9c368f..876d132 100644 --- a/test/export.test.ts +++ b/test/export.test.ts @@ -301,7 +301,7 @@ describe('Export test', () => { expect(result.exportFileName).toEqual('export_regular-version_GROUP_WITH_OPERATIONS_FROM_ONE_DOCUMENT_ONLY.zip') expect(result).toEqual(exportDocumentsMatcher([ exportDocumentMatcher('2.html'), - + exportDocumentMatcher('index.html'), exportDocumentMatcher('ls.html'), exportDocumentMatcher('resources/corporatelogo.png'), exportDocumentMatcher('resources/styles.css'), From 2327f8c34e750678fa7c784987585dcf9815263b Mon Sep 17 00:00:00 2001 From: Iurii Golovinskii Date: Wed, 13 Aug 2025 08:31:26 +0300 Subject: [PATCH 4/7] try 4 --- .../export-rest-document.strategy.ts | 18 +++++++++++++++--- test/export.test.ts | 1 + 2 files changed, 16 insertions(+), 3 deletions(-) diff --git a/src/strategies/export-rest-document.strategy.ts b/src/strategies/export-rest-document.strategy.ts index 798eccc..be12d40 100644 --- a/src/strategies/export-rest-document.strategy.ts +++ b/src/strategies/export-rest-document.strategy.ts @@ -14,9 +14,19 @@ * limitations under the License. */ -import { BuilderStrategy, BuildResult, BuildTypeContexts, ExportRestDocumentBuildConfig } from '../types' +import { + BuilderStrategy, + BuildResult, + BuildTypeContexts, + ExportDocument, + ExportRestDocumentBuildConfig, +} from '../types' import { getDocumentTitle, getSplittedVersionKey } from '../utils' -import { createCommonStaticExportDocuments, createSingleFileExportName } from '../utils/export' +import { + createCommonStaticExportDocuments, + createSingleFileExportName, + createUnknownExportDocument, generateIndexHtmlPage, +} from '../utils/export' import { createRestExportDocument } from '../apitypes/rest/rest.document' import { FILE_FORMAT_HTML } from '../consts' @@ -26,7 +36,7 @@ export class ExportRestDocumentStrategy implements BuilderStrategy { const { rawDocumentResolver, templateResolver, packageResolver } = builderContext(config) const { packageId, version: versionWithRevision, documentId, format, allowedOasExtensions } = config const [version] = getSplittedVersionKey(versionWithRevision) - + const generatedHtmlExportDocuments: ExportDocument[] = [] const file = await rawDocumentResolver( versionWithRevision, packageId, @@ -36,7 +46,9 @@ export class ExportRestDocumentStrategy implements BuilderStrategy { buildResult.exportDocuments.push(await createRestExportDocument(file.name, await file.text(), format, packageName, version, templateResolver, allowedOasExtensions)) if (format === FILE_FORMAT_HTML) { + const readme = await buildResult.exportDocuments.find(({ filename }) => filename.toLowerCase() === 'readme.md')?.data.text() buildResult.exportDocuments.push(...await createCommonStaticExportDocuments(packageName, version, templateResolver, buildResult.exportDocuments[0].filename)) + buildResult.exportDocuments.push(createUnknownExportDocument('index.html', await generateIndexHtmlPage(packageName, version, generatedHtmlExportDocuments, templateResolver, readme))) buildResult.exportFileName = createSingleFileExportName(packageId, version, getDocumentTitle(file.name), 'zip') return buildResult } diff --git a/test/export.test.ts b/test/export.test.ts index 876d132..4f48f7f 100644 --- a/test/export.test.ts +++ b/test/export.test.ts @@ -117,6 +117,7 @@ describe('Export test', () => { expect(result).toEqual(exportDocumentsMatcher([ exportDocumentMatcher('1.html'), exportDocumentMatcher('ls.html'), + exportDocumentMatcher('index.html'), exportDocumentMatcher('resources/corporatelogo.png'), exportDocumentMatcher('resources/styles.css'), ])) From 137186c9066b9c9ab14b28892e786b5ad310f032 Mon Sep 17 00:00:00 2001 From: Iurii Golovinskii Date: Thu, 14 Aug 2025 14:53:52 +0300 Subject: [PATCH 5/7] fixed bug with html in ExportRestDocumentStrategy --- src/strategies/export-rest-document.strategy.ts | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/src/strategies/export-rest-document.strategy.ts b/src/strategies/export-rest-document.strategy.ts index be12d40..1592dc2 100644 --- a/src/strategies/export-rest-document.strategy.ts +++ b/src/strategies/export-rest-document.strategy.ts @@ -25,7 +25,8 @@ import { getDocumentTitle, getSplittedVersionKey } from '../utils' import { createCommonStaticExportDocuments, createSingleFileExportName, - createUnknownExportDocument, generateIndexHtmlPage, + createUnknownExportDocument, + generateIndexHtmlPage, } from '../utils/export' import { createRestExportDocument } from '../apitypes/rest/rest.document' import { FILE_FORMAT_HTML } from '../consts' @@ -43,12 +44,10 @@ export class ExportRestDocumentStrategy implements BuilderStrategy { documentId, ) const { name: packageName } = await packageResolver(packageId) - buildResult.exportDocuments.push(await createRestExportDocument(file.name, await file.text(), format, packageName, version, templateResolver, allowedOasExtensions)) - + buildResult.exportDocuments.push(await createRestExportDocument(file.name, await file.text(), format, packageName, version, templateResolver, allowedOasExtensions, generatedHtmlExportDocuments)) if (format === FILE_FORMAT_HTML) { - const readme = await buildResult.exportDocuments.find(({ filename }) => filename.toLowerCase() === 'readme.md')?.data.text() buildResult.exportDocuments.push(...await createCommonStaticExportDocuments(packageName, version, templateResolver, buildResult.exportDocuments[0].filename)) - buildResult.exportDocuments.push(createUnknownExportDocument('index.html', await generateIndexHtmlPage(packageName, version, generatedHtmlExportDocuments, templateResolver, readme))) + buildResult.exportDocuments.push(createUnknownExportDocument('index.html', await generateIndexHtmlPage(packageName, version, generatedHtmlExportDocuments, templateResolver))) buildResult.exportFileName = createSingleFileExportName(packageId, version, getDocumentTitle(file.name), 'zip') return buildResult } From e37f0558df7993fc276b3a4cd273d0467294e6b5 Mon Sep 17 00:00:00 2001 From: Iurii Golovinskii Date: Thu, 14 Aug 2025 16:10:09 +0300 Subject: [PATCH 6/7] ready --- src/strategies/export-rest-document.strategy.ts | 2 +- .../export-rest-operations-group.strategy.ts | 5 ++--- src/strategies/export-version.strategy.ts | 12 ++++++------ src/utils/export.ts | 4 ++-- test/export.test.ts | 1 - 5 files changed, 11 insertions(+), 13 deletions(-) diff --git a/src/strategies/export-rest-document.strategy.ts b/src/strategies/export-rest-document.strategy.ts index 1592dc2..6d40754 100644 --- a/src/strategies/export-rest-document.strategy.ts +++ b/src/strategies/export-rest-document.strategy.ts @@ -46,7 +46,7 @@ export class ExportRestDocumentStrategy implements BuilderStrategy { const { name: packageName } = await packageResolver(packageId) buildResult.exportDocuments.push(await createRestExportDocument(file.name, await file.text(), format, packageName, version, templateResolver, allowedOasExtensions, generatedHtmlExportDocuments)) if (format === FILE_FORMAT_HTML) { - buildResult.exportDocuments.push(...await createCommonStaticExportDocuments(packageName, version, templateResolver, buildResult.exportDocuments[0].filename)) + buildResult.exportDocuments.push(...await createCommonStaticExportDocuments(packageName, version, templateResolver)) buildResult.exportDocuments.push(createUnknownExportDocument('index.html', await generateIndexHtmlPage(packageName, version, generatedHtmlExportDocuments, templateResolver))) buildResult.exportFileName = createSingleFileExportName(packageId, version, getDocumentTitle(file.name), 'zip') return buildResult diff --git a/src/strategies/export-rest-operations-group.strategy.ts b/src/strategies/export-rest-operations-group.strategy.ts index 3a84f24..7abb01f 100644 --- a/src/strategies/export-rest-operations-group.strategy.ts +++ b/src/strategies/export-rest-operations-group.strategy.ts @@ -78,7 +78,7 @@ async function exportMergedDocument(config: ExportRestOperationsGroupBuildConfig buildResult.exportDocuments.push(await createRestExportDocument(buildResult.merged.filename, JSON.stringify(buildResult.merged?.data), format, packageName, version, templateResolver, allowedOasExtensions)) if (format === FILE_FORMAT_HTML) { - buildResult.exportDocuments.push(...await createCommonStaticExportDocuments(packageName, version, templateResolver, buildResult.exportDocuments[0].filename)) + buildResult.exportDocuments.push(...await createCommonStaticExportDocuments(packageName, version, templateResolver)) } } @@ -107,8 +107,7 @@ async function exportReducedDocuments(config: ExportRestOperationsGroupBuildConf buildResult.exportDocuments.push(...transformedDocuments) if (format === FILE_FORMAT_HTML) { - const shouldAddIndexPage = generatedHtmlExportDocuments.length > 1 - buildResult.exportDocuments.push(...await createCommonStaticExportDocuments(packageName, version, templateResolver, shouldAddIndexPage ? 'index.html' : buildResult.exportDocuments[0].filename)) + buildResult.exportDocuments.push(...await createCommonStaticExportDocuments(packageName, version, templateResolver)) buildResult.exportDocuments.push(createUnknownExportDocument('index.html', await generateIndexHtmlPage(packageName, version, generatedHtmlExportDocuments, templateResolver))) } diff --git a/src/strategies/export-version.strategy.ts b/src/strategies/export-version.strategy.ts index 8a6eb2d..0b41c19 100644 --- a/src/strategies/export-version.strategy.ts +++ b/src/strategies/export-version.strategy.ts @@ -63,8 +63,7 @@ async function exportToHTML(config: ExportVersionBuildConfig, buildResult: Build const generatedHtmlExportDocuments: ExportDocument[] = [] const restDocuments = documents.filter(isRestDocument) - const hasReadme = !!documents.find(({ filename }) => filename.toLowerCase() === 'readme.md') - const shouldAddIndexPage = hasReadme && restDocuments.length > 0 || restDocuments.length > 1 + const shouldAddIndexPage = restDocuments.length > 0 const transformedDocuments = await Promise.all(documents.map(async document => { const { createExportDocument } = apiBuilders.find(({ types }) => types.includes(document.type)) || unknownApiBuilder const file = await rawDocumentResolver(versionWithRevision, packageId, document.slug) @@ -74,11 +73,12 @@ async function exportToHTML(config: ExportVersionBuildConfig, buildResult: Build buildResult.exportDocuments.push(...transformedDocuments) if (generatedHtmlExportDocuments.length > 0) { - buildResult.exportDocuments.push(...await createCommonStaticExportDocuments(packageName, version, templateResolver, shouldAddIndexPage ? 'index.html' : buildResult.exportDocuments[0].filename)) + buildResult.exportDocuments.push(...await createCommonStaticExportDocuments(packageName, version, templateResolver)) + } + if (shouldAddIndexPage) { + const readme = await buildResult.exportDocuments.find(({ filename }) => filename.toLowerCase() === 'readme.md')?.data.text() + buildResult.exportDocuments.push(createUnknownExportDocument('index.html', await generateIndexHtmlPage(packageName, version, generatedHtmlExportDocuments, templateResolver, readme))) } - - const readme = await buildResult.exportDocuments.find(({ filename }) => filename.toLowerCase() === 'readme.md')?.data.text() - buildResult.exportDocuments.push(createUnknownExportDocument('index.html', await generateIndexHtmlPage(packageName, version, generatedHtmlExportDocuments, templateResolver, readme))) } async function defaultExport(config: ExportVersionBuildConfig, buildResult: BuildResult, contexts: BuildTypeContexts): Promise { diff --git a/src/utils/export.ts b/src/utils/export.ts index fa0512b..d026aea 100644 --- a/src/utils/export.ts +++ b/src/utils/export.ts @@ -16,9 +16,9 @@ import { _TemplateResolver, ExportDocument } from '../types' import { getDocumentTitle } from './document' -export async function createCommonStaticExportDocuments(packageName: string, version: string, templateResolver: _TemplateResolver, backLinkFilename: string): Promise { +export async function createCommonStaticExportDocuments(packageName: string, version: string, templateResolver: _TemplateResolver): Promise { return [ - createUnknownExportDocument('ls.html', await generateLegalStatementPage(packageName, version, await templateResolver('ls.html'), backLinkFilename)), + createUnknownExportDocument('ls.html', await generateLegalStatementPage(packageName, version, await templateResolver('ls.html'), 'index.html')), createUnknownExportDocument('resources/corporatelogo.png', await templateResolver('resources/corporatelogo.png')), createUnknownExportDocument('resources/styles.css', await templateResolver('resources/styles.css')), ] diff --git a/test/export.test.ts b/test/export.test.ts index 4f48f7f..9a2ae9b 100644 --- a/test/export.test.ts +++ b/test/export.test.ts @@ -269,7 +269,6 @@ describe('Export test', () => { }) expect(result.exportFileName).toEqual('export_no-documents-version.zip') expect(result).toEqual(exportDocumentsMatcher([ - exportDocumentMatcher('index.html'), exportDocumentMatcher('Document.docx'), exportDocumentMatcher('README.md'), exportDocumentMatcher('Test.png'), From c792a3fbec1676405c58c228fc2ac5452a114ef2 Mon Sep 17 00:00:00 2001 From: Iurii Golovinskii Date: Mon, 18 Aug 2025 10:38:42 +0300 Subject: [PATCH 7/7] ready --- test/export.test.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test/export.test.ts b/test/export.test.ts index 9a2ae9b..01c19f8 100644 --- a/test/export.test.ts +++ b/test/export.test.ts @@ -254,7 +254,7 @@ describe('Export test', () => { exportDocumentMatcher('1.html'), exportDocumentMatcher('README.md'), - exportDocumentMatcher('index.html'), // contains index.html due to the presence of README + exportDocumentMatcher('index.html'), exportDocumentMatcher('ls.html'), exportDocumentMatcher('resources/corporatelogo.png'), exportDocumentMatcher('resources/styles.css'),