Skip to content

Commit ae2af54

Browse files
sserratasserrata
committed
feat: add --schemas-only flag to clean-api-docs commands
- Add --schemas-only option to clean-api-docs command - Add --schemas-only option to clean-api-docs:version command - When --schemas-only is used, only the schemas/ directory is cleaned - API, info, tag docs and sidebar files are left untouched - Update documentation in all README files
1 parent 91b67a7 commit ae2af54

File tree

4 files changed

+84
-45
lines changed

4 files changed

+84
-45
lines changed

‎README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -349,6 +349,14 @@ yarn docusaurus clean-api-docs all --all-versions
349349

350350
> This will clean API docs for all versions of all the OpenAPI specification (OAS) files referenced in your `docusaurus-plugin-openapi-docs` config.
351351
352+
To clean only schema docs while leaving API, info, and tag docs untouched, use the `--schemas-only` flag:
353+
354+
```bash
355+
yarn docusaurus clean-api-docs petstore --schemas-only
356+
```
357+
358+
> The `--schemas-only` flag is also available for `clean-api-docs:version`.
359+
352360
### Versioning OpenAPI docs
353361

354362
To generate _all_ versioned OpenAPI docs, run the following command from the root directory of your project:

‎demo/docs/intro.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -391,6 +391,12 @@ Example:
391391
yarn docusaurus clean-api-docs petstore
392392
```
393393

394+
To clean only schema docs while leaving API, info, and tag docs untouched, use the `--schemas-only` flag:
395+
396+
```bash title="cleaning only schema docs for 'petstore'"
397+
yarn docusaurus clean-api-docs petstore --schemas-only
398+
```
399+
394400
### Versioning OpenAPI docs
395401

396402
To generate _all_ versioned OpenAPI docs, run the following command from the root directory of your project:

‎packages/docusaurus-plugin-openapi-docs/README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -370,6 +370,14 @@ yarn docusaurus clean-api-docs all --all-versions
370370

371371
> This will clean API docs for all versions of all the OpenAPI specification (OAS) files referenced in your `docusaurus-plugin-openapi-docs` config.
372372
373+
To clean only schema docs while leaving API, info, and tag docs untouched, use the `--schemas-only` flag:
374+
375+
```bash
376+
yarn docusaurus clean-api-docs petstore --schemas-only
377+
```
378+
379+
> The `--schemas-only` flag is also available for `clean-api-docs:version`.
380+
373381
### Versioning OpenAPI docs
374382

375383
To generate _all_ versioned OpenAPI docs, run the following command from the root directory of your project:

‎packages/docusaurus-plugin-openapi-docs/src/index.ts‎

Lines changed: 62 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -491,29 +491,53 @@ custom_edit_url: null
491491
}
492492
}
493493

494-
async function cleanApiDocs(options: APIOptions) {
494+
async function cleanApiDocs(options: APIOptions, schemasOnly = false) {
495495
const { outputDir } = options;
496496
const apiDir = posixPath(path.join(siteDir, outputDir));
497-
const apiMdxFiles = await Globby(["*.api.mdx", "*.info.mdx", "*.tag.mdx"], {
498-
cwd: path.resolve(apiDir),
499-
deep: 1,
500-
});
501-
const sidebarFile = await Globby(["sidebar.js", "sidebar.ts"], {
502-
cwd: path.resolve(apiDir),
503-
deep: 1,
504-
});
505-
apiMdxFiles.map((mdx) =>
506-
fs.unlink(`${apiDir}/${mdx}`, (err) => {
507-
if (err) {
508-
console.error(
509-
chalk.red(`Cleanup failed for "${apiDir}/${mdx}"`),
510-
chalk.yellow(err)
511-
);
512-
} else {
513-
console.log(chalk.green(`Cleanup succeeded for "${apiDir}/${mdx}"`));
497+
498+
// When schemasOnly is true, only clean the schemas directory
499+
if (!schemasOnly) {
500+
const apiMdxFiles = await Globby(
501+
["*.api.mdx", "*.info.mdx", "*.tag.mdx"],
502+
{
503+
cwd: path.resolve(apiDir),
504+
deep: 1,
514505
}
515-
})
516-
);
506+
);
507+
const sidebarFile = await Globby(["sidebar.js", "sidebar.ts"], {
508+
cwd: path.resolve(apiDir),
509+
deep: 1,
510+
});
511+
apiMdxFiles.map((mdx) =>
512+
fs.unlink(`${apiDir}/${mdx}`, (err) => {
513+
if (err) {
514+
console.error(
515+
chalk.red(`Cleanup failed for "${apiDir}/${mdx}"`),
516+
chalk.yellow(err)
517+
);
518+
} else {
519+
console.log(
520+
chalk.green(`Cleanup succeeded for "${apiDir}/${mdx}"`)
521+
);
522+
}
523+
})
524+
);
525+
526+
sidebarFile.map((sidebar) =>
527+
fs.unlink(`${apiDir}/${sidebar}`, (err) => {
528+
if (err) {
529+
console.error(
530+
chalk.red(`Cleanup failed for "${apiDir}/${sidebar}"`),
531+
chalk.yellow(err)
532+
);
533+
} else {
534+
console.log(
535+
chalk.green(`Cleanup succeeded for "${apiDir}/${sidebar}"`)
536+
);
537+
}
538+
})
539+
);
540+
}
517541

518542
try {
519543
fs.rmSync(`${apiDir}/schemas`, { recursive: true });
@@ -526,21 +550,6 @@ custom_edit_url: null
526550
);
527551
}
528552
}
529-
530-
sidebarFile.map((sidebar) =>
531-
fs.unlink(`${apiDir}/${sidebar}`, (err) => {
532-
if (err) {
533-
console.error(
534-
chalk.red(`Cleanup failed for "${apiDir}/${sidebar}"`),
535-
chalk.yellow(err)
536-
);
537-
} else {
538-
console.log(
539-
chalk.green(`Cleanup succeeded for "${apiDir}/${sidebar}"`)
540-
);
541-
}
542-
})
543-
);
544553
}
545554

546555
async function generateVersions(versions: object, outputDir: string) {
@@ -641,22 +650,24 @@ custom_edit_url: null
641650
}
642651
}
643652

644-
async function cleanAllVersions(options: APIOptions) {
653+
async function cleanAllVersions(options: APIOptions, schemasOnly = false) {
645654
const parentOptions = Object.assign({}, options);
646655

647656
const { versions } = parentOptions as any;
648657

649658
delete parentOptions.versions;
650659

651660
if (versions != null && Object.keys(versions).length > 0) {
652-
await cleanVersions(parentOptions.outputDir);
661+
if (!schemasOnly) {
662+
await cleanVersions(parentOptions.outputDir);
663+
}
653664
Object.keys(versions).forEach(async (key) => {
654665
const versionOptions = versions[key];
655666
const mergedOptions = {
656667
...parentOptions,
657668
...versionOptions,
658669
};
659-
await cleanApiDocs(mergedOptions);
670+
await cleanApiDocs(mergedOptions, schemasOnly);
660671
});
661672
}
662673
}
@@ -844,10 +855,12 @@ custom_edit_url: null
844855
.arguments("<id>")
845856
.option("-p, --plugin-id <plugin>", "OpenAPI docs plugin ID.")
846857
.option("--all-versions", "Clean all versions.")
858+
.option("--schemas-only", "Clean only schema docs.")
847859
.action(async (id, instance) => {
848860
const options = instance.opts();
849861
const pluginId = options.pluginId;
850862
const allVersions = options.allVersions;
863+
const schemasOnly = options.schemasOnly;
851864
const pluginInstances = getPluginInstances(plugins);
852865
let targetConfig: any;
853866
if (pluginId) {
@@ -880,16 +893,16 @@ custom_edit_url: null
880893
);
881894
} else {
882895
Object.keys(targetConfig).forEach(async function (key) {
883-
await cleanApiDocs(targetConfig[key]);
896+
await cleanApiDocs(targetConfig[key], schemasOnly);
884897
if (allVersions) {
885-
await cleanAllVersions(targetConfig[key]);
898+
await cleanAllVersions(targetConfig[key], schemasOnly);
886899
}
887900
});
888901
}
889902
} else {
890-
await cleanApiDocs(targetConfig[id]);
903+
await cleanApiDocs(targetConfig[id], schemasOnly);
891904
if (allVersions) {
892-
await cleanAllVersions(targetConfig[id]);
905+
await cleanAllVersions(targetConfig[id], schemasOnly);
893906
}
894907
}
895908
});
@@ -902,9 +915,11 @@ custom_edit_url: null
902915
.usage("<id:version>")
903916
.arguments("<id:version>")
904917
.option("-p, --plugin-id <plugin>", "OpenAPI docs plugin ID.")
918+
.option("--schemas-only", "Clean only schema docs.")
905919
.action(async (id, instance) => {
906920
const options = instance.opts();
907921
const pluginId = options.pluginId;
922+
const schemasOnly = options.schemasOnly;
908923
const pluginInstances = getPluginInstances(plugins);
909924
let targetConfig: any;
910925
if (pluginId) {
@@ -940,14 +955,16 @@ custom_edit_url: null
940955
"Can't use id 'all' for OpenAPI docs versions configuration key."
941956
);
942957
} else {
943-
await cleanVersions(parentConfig.outputDir);
958+
if (!schemasOnly) {
959+
await cleanVersions(parentConfig.outputDir);
960+
}
944961
Object.keys(versions).forEach(async (key) => {
945962
const versionConfig = versions[key];
946963
const mergedConfig = {
947964
...parentConfig,
948965
...versionConfig,
949966
};
950-
await cleanApiDocs(mergedConfig);
967+
await cleanApiDocs(mergedConfig, schemasOnly);
951968
});
952969
}
953970
} else {
@@ -956,7 +973,7 @@ custom_edit_url: null
956973
...parentConfig,
957974
...versionConfig,
958975
};
959-
await cleanApiDocs(mergedConfig);
976+
await cleanApiDocs(mergedConfig, schemasOnly);
960977
}
961978
});
962979
},

0 commit comments

Comments
 (0)