@t0.labs/daxta 1.1.1 → 1.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +9 -9
- package/assets/empty.html +1 -1
- package/assets/example.html +75 -29
- package/assets/viewer.html +479 -134
- package/dist/build/build-spec.js +8 -6
- package/dist/cli/install.js +6 -6
- package/dist/cli/titles.js +34 -4
- package/dist/config.d.ts +6 -0
- package/dist/config.js +10 -1
- package/dist/fields/dto-fields.js +12 -2
- package/dist/jest/reporter.js +2 -2
- package/dist/serve/middleware.d.ts +7 -5
- package/dist/serve/middleware.js +11 -11
- package/dist/serve/paths.d.ts +2 -1
- package/dist/serve/paths.js +9 -3
- package/package.json +1 -1
package/dist/build/build-spec.js
CHANGED
|
@@ -718,22 +718,24 @@ function mergeSpecs(existing, fresh) {
|
|
|
718
718
|
function countOperations(spec) {
|
|
719
719
|
return Object.values(spec.paths).reduce((count, pathItem) => count + Object.keys(pathItem).length, 0);
|
|
720
720
|
}
|
|
721
|
+
function pngDataUri(filePath) {
|
|
722
|
+
return (0, fs_1.existsSync)(filePath) ? `data:image/png;base64,${(0, fs_1.readFileSync)(filePath).toString('base64')}` : '';
|
|
723
|
+
}
|
|
721
724
|
function toStandaloneHtml(spec) {
|
|
722
725
|
const template = (0, fs_1.readFileSync)((0, paths_1.getViewerAssetPath)(), 'utf8');
|
|
723
|
-
const
|
|
724
|
-
const
|
|
725
|
-
? `data:image/png;base64,${(0, fs_1.readFileSync)(faviconPath).toString('base64')}`
|
|
726
|
-
: '';
|
|
726
|
+
const faviconUri = pngDataUri((0, paths_1.getFaviconAssetPath)());
|
|
727
|
+
const faviconLightUri = pngDataUri((0, paths_1.getFaviconLightAssetPath)()) || faviconUri;
|
|
727
728
|
return template
|
|
728
729
|
.replace('__SPEC_JSON__', JSON.stringify(spec).replace(/</g, '\\u003c'))
|
|
729
|
-
.replaceAll('__FAVICON_DATA_URI__', faviconUri)
|
|
730
|
+
.replaceAll('__FAVICON_DATA_URI__', faviconUri)
|
|
731
|
+
.replaceAll('__FAVICON_LIGHT_DATA_URI__', faviconLightUri);
|
|
730
732
|
}
|
|
731
733
|
function viewerTemplateNewerThanHtml() {
|
|
732
734
|
if (!(0, fs_1.existsSync)((0, paths_1.getHtmlPath)()))
|
|
733
735
|
return true;
|
|
734
736
|
const htmlMtime = (0, fs_1.statSync)((0, paths_1.getHtmlPath)()).mtimeMs;
|
|
735
737
|
const newerThan = (filePath) => (0, fs_1.existsSync)(filePath) && (0, fs_1.statSync)(filePath).mtimeMs > htmlMtime;
|
|
736
|
-
return newerThan((0, paths_1.getViewerAssetPath)()) || newerThan((0, paths_1.getFaviconAssetPath)());
|
|
738
|
+
return newerThan((0, paths_1.getViewerAssetPath)()) || newerThan((0, paths_1.getFaviconAssetPath)()) || newerThan((0, paths_1.getFaviconLightAssetPath)());
|
|
737
739
|
}
|
|
738
740
|
function applyViewerMeta(spec) {
|
|
739
741
|
const info = specInfo();
|
package/dist/cli/install.js
CHANGED
|
@@ -118,7 +118,7 @@ export default defineConfig({
|
|
|
118
118
|
baseUrl: 'http://localhost:3000',
|
|
119
119
|
controllersRoot: 'src',
|
|
120
120
|
outDir: '.daxta/out',
|
|
121
|
-
docsPath: '/
|
|
121
|
+
docsPath: '/docs',
|
|
122
122
|
treeLayout: 'role-resource',
|
|
123
123
|
treeSkipParams: true,
|
|
124
124
|
exampleLabelStyle: 'status-title-case',
|
|
@@ -158,7 +158,7 @@ function ensureGitignore(cwd, dryRun) {
|
|
|
158
158
|
return added.map((e) => `.gitignore += ${e}`);
|
|
159
159
|
}
|
|
160
160
|
const ENV_CANDIDATES = ['.env', '.env.local', '.env.development', '.env.development.local'];
|
|
161
|
-
/** Ensure DAXTA_DOCS is present (default
|
|
161
|
+
/** Ensure DAXTA_DOCS is present (default on). Mirrors uninstall strip. */
|
|
162
162
|
function ensureEnvDaxtaDocs(cwd, dryRun) {
|
|
163
163
|
for (const name of ENV_CANDIDATES) {
|
|
164
164
|
const filePath = path.join(cwd, name);
|
|
@@ -171,7 +171,7 @@ function ensureEnvDaxtaDocs(cwd, dryRun) {
|
|
|
171
171
|
const targetName = ENV_CANDIDATES.find((name) => (0, fs_1.existsSync)(path.join(cwd, name))) ?? '.env';
|
|
172
172
|
const targetPath = path.join(cwd, targetName);
|
|
173
173
|
const created = !(0, fs_1.existsSync)(targetPath);
|
|
174
|
-
const line = 'DAXTA_DOCS=
|
|
174
|
+
const line = 'DAXTA_DOCS=on';
|
|
175
175
|
if (!dryRun) {
|
|
176
176
|
if (created) {
|
|
177
177
|
(0, fs_1.writeFileSync)(targetPath, `${line}\n`);
|
|
@@ -182,7 +182,7 @@ function ensureEnvDaxtaDocs(cwd, dryRun) {
|
|
|
182
182
|
(0, fs_1.writeFileSync)(targetPath, next);
|
|
183
183
|
}
|
|
184
184
|
}
|
|
185
|
-
return created ? `created ${targetName} (+ DAXTA_DOCS=
|
|
185
|
+
return created ? `created ${targetName} (+ DAXTA_DOCS=on)` : `${targetName} += DAXTA_DOCS=on`;
|
|
186
186
|
}
|
|
187
187
|
function runPackageInstall(cwd, pm, version, dryRun) {
|
|
188
188
|
if (dryRun)
|
|
@@ -344,7 +344,7 @@ async function installDaxta(options = {}) {
|
|
|
344
344
|
}
|
|
345
345
|
(0, ui_1.box)('Ready', [
|
|
346
346
|
`${ui_1.c.mint('✔')} ${ui_1.c.bold(project)} · DAxTA ${ui_1.c.gold(`v${version}`)}`,
|
|
347
|
-
`${ui_1.c.dim('api docs')} ${ui_1.c.ice('/
|
|
347
|
+
`${ui_1.c.dim('api docs')} ${ui_1.c.ice('/docs')} · ${ui_1.c.ice('DAXTA_DOCS=on')}`,
|
|
348
348
|
`${ui_1.c.dim('tests')} same script — titles first, spec after`,
|
|
349
349
|
`${ui_1.c.dim('retune')} ${ui_1.c.ice('daxta tree')} · ${ui_1.c.ice('daxta titles')}`,
|
|
350
350
|
]);
|
|
@@ -356,7 +356,7 @@ async function installDaxta(options = {}) {
|
|
|
356
356
|
},
|
|
357
357
|
{
|
|
358
358
|
cmd: `${pm} start:dev`,
|
|
359
|
-
why: 'open /
|
|
359
|
+
why: 'open /docs (DAXTA_DOCS=on already in .env)',
|
|
360
360
|
},
|
|
361
361
|
]);
|
|
362
362
|
}
|
package/dist/cli/titles.js
CHANGED
|
@@ -13,21 +13,23 @@ async function pickFromSuggestions(finding, extra, validate) {
|
|
|
13
13
|
if (extra)
|
|
14
14
|
console.log(` ${ui_1.c.dim(extra)}`);
|
|
15
15
|
if (!suggestions.length) {
|
|
16
|
-
console.log(` ${ui_1.c.gold('no auto suggestion')} ${ui_1.c.dim('— type a title, or s to skip')}`);
|
|
16
|
+
console.log(` ${ui_1.c.gold('no auto suggestion')} ${ui_1.c.dim('— type a title, or s to skip one, n to skip all')}`);
|
|
17
17
|
}
|
|
18
18
|
suggestions.forEach((name, index) => {
|
|
19
19
|
const mark = index === 0 ? ui_1.c.dim(' recommended') : '';
|
|
20
20
|
console.log(` ${ui_1.c.ice(String(index + 1))} ${name}${mark}`);
|
|
21
21
|
});
|
|
22
22
|
console.log(suggestions.length
|
|
23
|
-
? ` ${ui_1.c.dim('Enter = 1')} ${ui_1.c.dim('·')} ${ui_1.c.ice('a')} remaining auto ${ui_1.c.dim('·')} ${ui_1.c.ice('s')} skip ${ui_1.c.dim('·')} ${ui_1.c.ice('c')} custom`
|
|
24
|
-
: ` ${ui_1.c.ice('c')} custom ${ui_1.c.dim('·')} ${ui_1.c.ice('s')} skip`);
|
|
23
|
+
? ` ${ui_1.c.dim('Enter = 1')} ${ui_1.c.dim('·')} ${ui_1.c.ice('a')} remaining auto ${ui_1.c.dim('·')} ${ui_1.c.ice('s')} skip one ${ui_1.c.dim('·')} ${ui_1.c.ice('n')} skip all ${ui_1.c.dim('·')} ${ui_1.c.ice('c')} custom`
|
|
24
|
+
: ` ${ui_1.c.ice('c')} custom ${ui_1.c.dim('·')} ${ui_1.c.ice('s')} skip one ${ui_1.c.dim('·')} ${ui_1.c.ice('n')} skip all`);
|
|
25
25
|
const answer = (await (0, ui_1.readlineAsk)(` ${ui_1.c.ice('›')} `)).trim();
|
|
26
26
|
const lower = answer.toLowerCase();
|
|
27
27
|
if (!answer)
|
|
28
28
|
return suggestions[0] ? suggestions[0] : 'skip';
|
|
29
29
|
if (lower === 's')
|
|
30
30
|
return 'skip';
|
|
31
|
+
if (lower === 'n' || lower === 'no' || lower === 'skip-all' || lower === 'skipall')
|
|
32
|
+
return 'skip-all';
|
|
31
33
|
if (lower === 'a' || lower === 'all')
|
|
32
34
|
return 'all';
|
|
33
35
|
if (lower === 'y' || lower === 'yes')
|
|
@@ -133,7 +135,14 @@ async function runTitleCheck(options) {
|
|
|
133
135
|
console.log(` ${ui_1.c.dim('it()+')} creates mock tbs when cyprus payload shape`);
|
|
134
136
|
console.log(` ${ui_1.c.dim('it()-')} returns error when tax id already exists`);
|
|
135
137
|
console.log(` ${ui_1.c.dim('label')} 201 — cyprus payload shape`);
|
|
136
|
-
|
|
138
|
+
const start = await (0, ui_1.readlineAsk)(` ${ui_1.c.gold('?')} Review test names now?\n` +
|
|
139
|
+
` ${ui_1.c.dim('Y')} yes · ${ui_1.c.dim('n')} skip all\n ${ui_1.c.ice('›')} `);
|
|
140
|
+
if (!start || /^n(o)?$/i.test(start)) {
|
|
141
|
+
console.log(` ${ui_1.c.dim('skipped')} ${ui_1.c.ice('daxta titles')} ${ui_1.c.dim('anytime')}`);
|
|
142
|
+
console.log('');
|
|
143
|
+
return 0;
|
|
144
|
+
}
|
|
145
|
+
console.log(` ${ui_1.c.gold(String(total))} to review — ${ui_1.c.ice('y')} one recommended, ${ui_1.c.ice('a')} all remaining, ${ui_1.c.ice('s')} skip one, ${ui_1.c.ice('n')} skip all.`);
|
|
137
146
|
let written = 0;
|
|
138
147
|
let skipped = 0;
|
|
139
148
|
for (let i = 0; i < report.titles.length; i += 1) {
|
|
@@ -145,6 +154,14 @@ async function runTitleCheck(options) {
|
|
|
145
154
|
skipped += rest.skipped;
|
|
146
155
|
for (const pending of rest.pending) {
|
|
147
156
|
const customChoice = await pickFromSuggestions(pending, `docs would show ${pending.path} — custom title required`, test_title_1.isHumanOperationTitle);
|
|
157
|
+
if (customChoice === 'skip-all') {
|
|
158
|
+
skipped += rest.pending.length;
|
|
159
|
+
console.log(` ${ui_1.c.dim('skipped remaining')}`);
|
|
160
|
+
console.log('');
|
|
161
|
+
console.log(` ${ui_1.c.mint('✔')} ${written} updated ${ui_1.c.dim(`${skipped} skipped`)}`);
|
|
162
|
+
console.log('');
|
|
163
|
+
return options.strict && skipped > 0 ? 1 : 0;
|
|
164
|
+
}
|
|
148
165
|
if (!customChoice || customChoice === 'skip' || customChoice === 'all') {
|
|
149
166
|
skipped += 1;
|
|
150
167
|
continue;
|
|
@@ -161,6 +178,14 @@ async function runTitleCheck(options) {
|
|
|
161
178
|
console.log('');
|
|
162
179
|
return options.strict && skipped > 0 ? 1 : 0;
|
|
163
180
|
}
|
|
181
|
+
if (choice === 'skip-all') {
|
|
182
|
+
skipped += report.titles.length - i + report.cases.length;
|
|
183
|
+
console.log(` ${ui_1.c.dim('skipped remaining')}`);
|
|
184
|
+
console.log('');
|
|
185
|
+
console.log(` ${ui_1.c.mint('✔')} ${written} updated ${ui_1.c.dim(`${skipped} skipped`)}`);
|
|
186
|
+
console.log('');
|
|
187
|
+
return options.strict && skipped > 0 ? 1 : 0;
|
|
188
|
+
}
|
|
164
189
|
if (!choice || choice === 'skip') {
|
|
165
190
|
skipped += 1;
|
|
166
191
|
continue;
|
|
@@ -183,6 +208,11 @@ async function runTitleCheck(options) {
|
|
|
183
208
|
skipped += rest.skipped;
|
|
184
209
|
break;
|
|
185
210
|
}
|
|
211
|
+
if (choice === 'skip-all') {
|
|
212
|
+
skipped += report.cases.length - i;
|
|
213
|
+
console.log(` ${ui_1.c.dim('skipped remaining')}`);
|
|
214
|
+
break;
|
|
215
|
+
}
|
|
186
216
|
if (!choice || choice === 'skip') {
|
|
187
217
|
skipped += 1;
|
|
188
218
|
continue;
|
package/dist/config.d.ts
CHANGED
|
@@ -47,6 +47,10 @@ export type DaxtaConfig = {
|
|
|
47
47
|
exampleLabelStyle?: ExampleLabelStyle;
|
|
48
48
|
port?: number;
|
|
49
49
|
fieldsFile?: string;
|
|
50
|
+
/**
|
|
51
|
+
* URL prefix for the viewer. Default `/docs`.
|
|
52
|
+
* Override with env `DAXTA_DOCS_PATH` (e.g. `/docs` or `docs`).
|
|
53
|
+
*/
|
|
50
54
|
docsPath?: string;
|
|
51
55
|
/**
|
|
52
56
|
* Persisted Try-it env/header store (survives rebuild). Default `.daxta/viewer-store.json`.
|
|
@@ -67,6 +71,8 @@ export type DaxtaConfig = {
|
|
|
67
71
|
treePathSegments?: (pathTemplate: string) => string[] | undefined;
|
|
68
72
|
};
|
|
69
73
|
export type ResolvedDaxtaConfig = Required<Pick<DaxtaConfig, 'workspace' | 'baseUrl' | 'controllersRoot' | 'outDir' | 'treeLayout' | 'treePathOverrides' | 'treeSkipParams' | 'exampleLabelStyle' | 'port' | 'fieldsFile' | 'docsPath' | 'viewerStoreFile'>> & DaxtaConfig;
|
|
74
|
+
export declare const DEFAULT_DOCS_PATH = "/docs";
|
|
75
|
+
export declare function normalizeDocsPath(raw?: string | null): string;
|
|
70
76
|
export declare function defineConfig(config: DaxtaConfig): DaxtaConfig;
|
|
71
77
|
export declare function normalizeTreeLayout(layout: TreeLayout | LegacyTreeLayout | undefined): TreeLayout;
|
|
72
78
|
export declare function resolveConfig(cwd?: string, overrides?: DaxtaConfig): ResolvedDaxtaConfig;
|
package/dist/config.js
CHANGED
|
@@ -33,6 +33,8 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
33
33
|
};
|
|
34
34
|
})();
|
|
35
35
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
|
+
exports.DEFAULT_DOCS_PATH = void 0;
|
|
37
|
+
exports.normalizeDocsPath = normalizeDocsPath;
|
|
36
38
|
exports.defineConfig = defineConfig;
|
|
37
39
|
exports.normalizeTreeLayout = normalizeTreeLayout;
|
|
38
40
|
exports.resolveConfig = resolveConfig;
|
|
@@ -52,13 +54,19 @@ const DEFAULTS = {
|
|
|
52
54
|
exampleLabelStyle: 'status-title-case',
|
|
53
55
|
port: 5199,
|
|
54
56
|
fieldsFile: '.daxta/out/fields.json',
|
|
55
|
-
docsPath: '/
|
|
57
|
+
docsPath: '/docs',
|
|
56
58
|
viewerStoreFile: '.daxta/viewer-store.json',
|
|
57
59
|
envPresets: {
|
|
58
60
|
local: { baseUrl: 'http://localhost:3000' },
|
|
59
61
|
},
|
|
60
62
|
};
|
|
61
63
|
let cached = null;
|
|
64
|
+
exports.DEFAULT_DOCS_PATH = '/docs';
|
|
65
|
+
function normalizeDocsPath(raw) {
|
|
66
|
+
const value = String(raw ?? exports.DEFAULT_DOCS_PATH).trim() || exports.DEFAULT_DOCS_PATH;
|
|
67
|
+
const withSlash = value.startsWith('/') ? value : `/${value}`;
|
|
68
|
+
return withSlash.replace(/\/$/, '') || exports.DEFAULT_DOCS_PATH;
|
|
69
|
+
}
|
|
62
70
|
function defineConfig(config) {
|
|
63
71
|
return config;
|
|
64
72
|
}
|
|
@@ -106,6 +114,7 @@ function resolveConfig(cwd = process.cwd(), overrides) {
|
|
|
106
114
|
if (merged.exampleLabelStyle == null)
|
|
107
115
|
merged.exampleLabelStyle = DEFAULTS.exampleLabelStyle;
|
|
108
116
|
merged.envPresets = normalizeEnvPresets(merged.envPresets, merged.baseUrl);
|
|
117
|
+
merged.docsPath = normalizeDocsPath(process.env.DAXTA_DOCS_PATH || merged.docsPath);
|
|
109
118
|
merged.controllersRoot = path.isAbsolute(merged.controllersRoot)
|
|
110
119
|
? merged.controllersRoot
|
|
111
120
|
: path.join(cwd, merged.controllersRoot);
|
|
@@ -47,9 +47,18 @@ const path = __importStar(require("path"));
|
|
|
47
47
|
require("reflect-metadata");
|
|
48
48
|
const storage_1 = require("class-transformer/cjs/storage");
|
|
49
49
|
const class_validator_1 = require("class-validator");
|
|
50
|
-
const
|
|
50
|
+
const tsImport = __importStar(require("typescript"));
|
|
51
51
|
const config_1 = require("../config");
|
|
52
52
|
const path_util_1 = require("../path.util");
|
|
53
|
+
function loadTypescript() {
|
|
54
|
+
const mod = tsImport;
|
|
55
|
+
if (mod.ScriptTarget && mod.ScriptTarget.Latest != null)
|
|
56
|
+
return mod;
|
|
57
|
+
if (mod.default?.ScriptTarget && mod.default.ScriptTarget.Latest != null)
|
|
58
|
+
return mod.default;
|
|
59
|
+
return mod;
|
|
60
|
+
}
|
|
61
|
+
const ts = loadTypescript();
|
|
53
62
|
function controllerRoot() {
|
|
54
63
|
return (0, config_1.getConfig)().controllersRoot;
|
|
55
64
|
}
|
|
@@ -182,7 +191,8 @@ function loadDto(filePath, exportName) {
|
|
|
182
191
|
}
|
|
183
192
|
function parseController(filePath) {
|
|
184
193
|
const text = (0, fs_1.readFileSync)(filePath, 'utf8');
|
|
185
|
-
const
|
|
194
|
+
const scriptTarget = ts.ScriptTarget?.Latest ?? 99;
|
|
195
|
+
const source = ts.createSourceFile(filePath, text, scriptTarget, true);
|
|
186
196
|
const imports = collectImports(source, filePath);
|
|
187
197
|
const routes = [];
|
|
188
198
|
for (const stmt of source.statements) {
|
package/dist/jest/reporter.js
CHANGED
|
@@ -15,10 +15,10 @@ function printDocsReady(hits, operations) {
|
|
|
15
15
|
console.log('');
|
|
16
16
|
console.log(` ${bold('API docs ready')}`);
|
|
17
17
|
console.log(` ${dim('│')} ${green('✔')} ${cyan(url)} ${dim(`(${hits} hits · ${operations} ops)`)}`);
|
|
18
|
-
console.log(` ${dim('│')} ${dim('DAXTA_DOCS=
|
|
18
|
+
console.log(` ${dim('│')} ${dim('DAXTA_DOCS=on')} required on app start`);
|
|
19
19
|
console.log('');
|
|
20
20
|
console.log(` ${bold('Next')}`);
|
|
21
|
-
console.log(` ${cyan('$')} ${bold('DAXTA_DOCS=
|
|
21
|
+
console.log(` ${cyan('$')} ${bold('DAXTA_DOCS=on pnpm start:dev')}`);
|
|
22
22
|
console.log(` ${dim(`open ${url}`)}`);
|
|
23
23
|
console.log('');
|
|
24
24
|
}
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
export type ApiDocsOptions = {
|
|
2
|
-
/** URL prefix for the API docs viewer. Default from config (`docsPath`) or `/
|
|
2
|
+
/** URL prefix for the API docs viewer. Default from config (`docsPath`) / `DAXTA_DOCS_PATH` or `/docs`. */
|
|
3
3
|
basePath?: string;
|
|
4
4
|
};
|
|
5
5
|
type LooseRequest = {
|
|
@@ -22,7 +22,7 @@ type LooseResponse = {
|
|
|
22
22
|
};
|
|
23
23
|
export type ApiDocsHandler = (req: LooseRequest, res: LooseResponse, next: (error?: unknown) => void) => void | Promise<void>;
|
|
24
24
|
/**
|
|
25
|
-
* Express / Nest handler that serves generated API docs under `/
|
|
25
|
+
* Express / Nest handler that serves generated API docs under `/docs`
|
|
26
26
|
* (or `basePath`), Try-it proxy at `/__proxy`, and env store at `{base}/env.json`.
|
|
27
27
|
*/
|
|
28
28
|
export declare function apiDocsHandler(options?: ApiDocsOptions): ApiDocsHandler;
|
|
@@ -30,9 +30,11 @@ export declare function apiDocsHandler(options?: ApiDocsOptions): ApiDocsHandler
|
|
|
30
30
|
* Mount generated API docs on a Nest / Express app (`app.use(...)`).
|
|
31
31
|
*
|
|
32
32
|
* Requires `DAXTA_DOCS` in the environment:
|
|
33
|
-
* - missing / empty → throws
|
|
34
|
-
* - `
|
|
35
|
-
* - `
|
|
33
|
+
* - missing / empty → throws
|
|
34
|
+
* - `on` → serve docs
|
|
35
|
+
* - `off` → no-op
|
|
36
|
+
*
|
|
37
|
+
* Path defaults to `/docs`. Override with `DAXTA_DOCS_PATH` or `docsPath` in config.
|
|
36
38
|
*/
|
|
37
39
|
export declare function apiDocs(app: {
|
|
38
40
|
use: (...handlers: unknown[]) => unknown;
|
package/dist/serve/middleware.js
CHANGED
|
@@ -96,11 +96,11 @@ async function readRequestJson(req) {
|
|
|
96
96
|
}
|
|
97
97
|
}
|
|
98
98
|
/**
|
|
99
|
-
* Express / Nest handler that serves generated API docs under `/
|
|
99
|
+
* Express / Nest handler that serves generated API docs under `/docs`
|
|
100
100
|
* (or `basePath`), Try-it proxy at `/__proxy`, and env store at `{base}/env.json`.
|
|
101
101
|
*/
|
|
102
102
|
function apiDocsHandler(options = {}) {
|
|
103
|
-
const basePath = (options.basePath ?? (0, paths_1.getDocsBasePath)()).replace(/\/$/, '') || '/
|
|
103
|
+
const basePath = (options.basePath ?? (0, paths_1.getDocsBasePath)()).replace(/\/$/, '') || '/docs';
|
|
104
104
|
return async (req, res, next) => {
|
|
105
105
|
const method = (req.method || 'GET').toUpperCase();
|
|
106
106
|
const pathname = requestPathname(req);
|
|
@@ -193,22 +193,22 @@ function apiDocsHandler(options = {}) {
|
|
|
193
193
|
* Mount generated API docs on a Nest / Express app (`app.use(...)`).
|
|
194
194
|
*
|
|
195
195
|
* Requires `DAXTA_DOCS` in the environment:
|
|
196
|
-
* - missing / empty → throws
|
|
197
|
-
* - `
|
|
198
|
-
* - `
|
|
196
|
+
* - missing / empty → throws
|
|
197
|
+
* - `on` → serve docs
|
|
198
|
+
* - `off` → no-op
|
|
199
|
+
*
|
|
200
|
+
* Path defaults to `/docs`. Override with `DAXTA_DOCS_PATH` or `docsPath` in config.
|
|
199
201
|
*/
|
|
200
202
|
function apiDocs(app, options = {}) {
|
|
201
203
|
const raw = process.env.DAXTA_DOCS;
|
|
202
204
|
if (raw == null || String(raw).trim() === '') {
|
|
203
|
-
throw new Error('DAxTA: DAXTA_DOCS is not set. Set DAXTA_DOCS=
|
|
205
|
+
throw new Error('DAxTA: DAXTA_DOCS is not set. Set DAXTA_DOCS=on or DAXTA_DOCS=off.');
|
|
204
206
|
}
|
|
205
207
|
const normalized = String(raw).trim().toLowerCase();
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
if (!enabled && !disabled) {
|
|
209
|
-
throw new Error(`DAxTA: invalid DAXTA_DOCS="${raw}". Use true/false (or 1/0).`);
|
|
208
|
+
if (normalized !== 'on' && normalized !== 'off') {
|
|
209
|
+
throw new Error(`DAxTA: invalid DAXTA_DOCS="${raw}". Use on or off.`);
|
|
210
210
|
}
|
|
211
|
-
if (
|
|
211
|
+
if (normalized === 'off')
|
|
212
212
|
return;
|
|
213
213
|
app.use(apiDocsHandler(options));
|
|
214
214
|
}
|
package/dist/serve/paths.d.ts
CHANGED
|
@@ -8,8 +8,9 @@ export declare function getViewerAssetPath(): string;
|
|
|
8
8
|
export declare function getEmptyViewerAssetPath(): string;
|
|
9
9
|
export declare function readEmptyDocsHtml(): Buffer;
|
|
10
10
|
export declare function getFaviconAssetPath(): string;
|
|
11
|
+
export declare function getFaviconLightAssetPath(): string;
|
|
11
12
|
export declare function getDocsBasePath(): string;
|
|
12
|
-
/** App-origin URL where generated API docs are served (e.g. `http://localhost:3000/
|
|
13
|
+
/** App-origin URL where generated API docs are served (e.g. `http://localhost:3000/docs`). */
|
|
13
14
|
export declare function getApiDocUrl(): string;
|
|
14
15
|
/** Paths and URL for the generated API docs artifact. */
|
|
15
16
|
export declare function getApiDocs(): {
|
package/dist/serve/paths.js
CHANGED
|
@@ -42,6 +42,7 @@ exports.getViewerAssetPath = getViewerAssetPath;
|
|
|
42
42
|
exports.getEmptyViewerAssetPath = getEmptyViewerAssetPath;
|
|
43
43
|
exports.readEmptyDocsHtml = readEmptyDocsHtml;
|
|
44
44
|
exports.getFaviconAssetPath = getFaviconAssetPath;
|
|
45
|
+
exports.getFaviconLightAssetPath = getFaviconLightAssetPath;
|
|
45
46
|
exports.getDocsBasePath = getDocsBasePath;
|
|
46
47
|
exports.getApiDocUrl = getApiDocUrl;
|
|
47
48
|
exports.getApiDocs = getApiDocs;
|
|
@@ -82,13 +83,18 @@ function readEmptyDocsHtml() {
|
|
|
82
83
|
return Buffer.from(EMPTY_DOCS_FALLBACK);
|
|
83
84
|
}
|
|
84
85
|
function getFaviconAssetPath() {
|
|
86
|
+
const dark = path.join(__dirname, '..', '..', 'assets', 'logo-dark.png');
|
|
87
|
+
if ((0, fs_1.existsSync)(dark))
|
|
88
|
+
return dark;
|
|
85
89
|
return path.join(__dirname, '..', '..', 'assets', 'favicon.png');
|
|
86
90
|
}
|
|
91
|
+
function getFaviconLightAssetPath() {
|
|
92
|
+
return path.join(__dirname, '..', '..', 'assets', 'logo-light.png');
|
|
93
|
+
}
|
|
87
94
|
function getDocsBasePath() {
|
|
88
|
-
|
|
89
|
-
return configured.startsWith('/') ? configured.replace(/\/$/, '') || '/api-docs' : `/${configured}`.replace(/\/$/, '');
|
|
95
|
+
return (0, config_1.normalizeDocsPath)(process.env.DAXTA_DOCS_PATH || (0, config_1.getConfig)().docsPath || config_1.DEFAULT_DOCS_PATH);
|
|
90
96
|
}
|
|
91
|
-
/** App-origin URL where generated API docs are served (e.g. `http://localhost:3000/
|
|
97
|
+
/** App-origin URL where generated API docs are served (e.g. `http://localhost:3000/docs`). */
|
|
92
98
|
function getApiDocUrl() {
|
|
93
99
|
const config = (0, config_1.getConfig)();
|
|
94
100
|
return `${String(config.baseUrl || '').replace(/\/$/, '')}${getDocsBasePath()}`;
|