@aomex/openapi 3.30.7 → 3.30.8-alpha.1030873.0
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/dist/index.d.ts +113 -66
- package/dist/index.js +484 -428
- package/dist/index.js.map +1 -1
- package/package.json +12 -12
package/dist/index.js
CHANGED
|
@@ -1,462 +1,518 @@
|
|
|
1
|
-
|
|
2
|
-
import { middleware } from "@aomex/common";
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
import "
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
}
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
1
|
+
import { createRequire } from "node:module";
|
|
2
|
+
import { I18n, createI18n, middleware } from "@aomex/common";
|
|
3
|
+
import { getFileValues, pathToFiles } from "@aomex/internal-file-import";
|
|
4
|
+
import path from "node:path";
|
|
5
|
+
import { mkdir, readFile, writeFile } from "node:fs/promises";
|
|
6
|
+
import YAML from "yaml";
|
|
7
|
+
import { bytes } from "@aomex/internal-tools";
|
|
8
|
+
import { Router, WebMiddleware, createEnvelopeOpenApiInjector } from "@aomex/web";
|
|
9
|
+
import snakeCase from "lodash.snakecase";
|
|
10
|
+
import { terminal } from "@aomex/console";
|
|
11
|
+
// \0rolldown/runtime.js
|
|
12
|
+
var __create = Object.create;
|
|
13
|
+
var __defProp = Object.defineProperty;
|
|
14
|
+
var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
|
|
15
|
+
var __getOwnPropNames = Object.getOwnPropertyNames;
|
|
16
|
+
var __getProtoOf = Object.getPrototypeOf;
|
|
17
|
+
var __hasOwnProp = Object.prototype.hasOwnProperty;
|
|
18
|
+
var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod, mod.exports), cb = null), mod.exports);
|
|
19
|
+
var __copyProps = (to, from, except, desc) => {
|
|
20
|
+
if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
|
|
21
|
+
key = keys[i];
|
|
22
|
+
if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
|
|
23
|
+
get: ((k) => from[k]).bind(null, key),
|
|
24
|
+
enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
|
|
25
|
+
});
|
|
26
|
+
}
|
|
27
|
+
return to;
|
|
28
|
+
};
|
|
29
|
+
var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", {
|
|
30
|
+
value: mod,
|
|
31
|
+
enumerable: true
|
|
32
|
+
}) : target, mod));
|
|
32
33
|
// src/lib/validate-openapi.ts
|
|
33
|
-
|
|
34
|
-
var
|
|
35
|
-
|
|
36
|
-
var
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
34
|
+
var import_cjs = /* @__PURE__ */ __toESM((/* @__PURE__ */ __commonJSMin(((exports, module) => {
|
|
35
|
+
var e = setTimeout;
|
|
36
|
+
function t(t, n) {
|
|
37
|
+
var u = n.useCachedSetTimeout ? e : setTimeout;
|
|
38
|
+
return new Promise((function(e) {
|
|
39
|
+
u(e, t);
|
|
40
|
+
}));
|
|
41
|
+
}
|
|
42
|
+
module.exports = function(e) {
|
|
43
|
+
var u = (arguments.length > 1 && void 0 !== arguments[1] ? arguments[1] : {}).useCachedSetTimeout, r = t(e, { useCachedSetTimeout: u });
|
|
44
|
+
function o(e) {
|
|
45
|
+
return r.then((function() {
|
|
46
|
+
return e;
|
|
47
|
+
}));
|
|
48
|
+
}
|
|
49
|
+
return o.then = function() {
|
|
50
|
+
return r.then.apply(r, arguments);
|
|
51
|
+
}, o.catch = Promise.resolve().catch, o;
|
|
52
|
+
};
|
|
53
|
+
})))(), 1);
|
|
54
|
+
const requireCJS = createRequire(import.meta.url);
|
|
55
|
+
let _spectral = null;
|
|
56
|
+
const initSpectral = () => {
|
|
57
|
+
if (!_spectral) {
|
|
58
|
+
const { Spectral } = requireCJS("@stoplight/spectral-core");
|
|
59
|
+
const { oas } = requireCJS("@stoplight/spectral-rulesets");
|
|
60
|
+
_spectral = new Spectral();
|
|
61
|
+
_spectral.setRuleset({
|
|
62
|
+
extends: oas,
|
|
63
|
+
rules: {
|
|
64
|
+
"info-contact": "off",
|
|
65
|
+
"info-description": "off"
|
|
66
|
+
}
|
|
67
|
+
});
|
|
68
|
+
}
|
|
69
|
+
return _spectral;
|
|
51
70
|
};
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
71
|
+
const validateOpenapi = async (document) => {
|
|
72
|
+
const result = {
|
|
73
|
+
warnings: [],
|
|
74
|
+
errors: []
|
|
75
|
+
};
|
|
76
|
+
(await initSpectral().run(document)).forEach((item) => {
|
|
77
|
+
result[item.severity === 0 ? "errors" : "warnings"].push({
|
|
78
|
+
path: item.path.map(String),
|
|
79
|
+
message: item.message
|
|
80
|
+
});
|
|
81
|
+
});
|
|
82
|
+
return result;
|
|
63
83
|
};
|
|
64
|
-
|
|
65
84
|
// src/lib/methods.ts
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
85
|
+
const methods = [
|
|
86
|
+
"get",
|
|
87
|
+
"post",
|
|
88
|
+
"put",
|
|
89
|
+
"patch",
|
|
90
|
+
"delete",
|
|
91
|
+
"options",
|
|
92
|
+
"head",
|
|
93
|
+
"trace"
|
|
75
94
|
];
|
|
76
|
-
|
|
77
95
|
// src/lib/hoist-parameter.ts
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
96
|
+
/**
|
|
97
|
+
* 同一个路径下,所有方法都有相同的parameter时,可以往上提取,这样能减小生成产物
|
|
98
|
+
*/
|
|
99
|
+
const methodParameterToPathParameter = (document) => {
|
|
100
|
+
pathLoop: for (const path of Object.values(document.paths)) {
|
|
101
|
+
const parametersHandler = {};
|
|
102
|
+
let methodCounter = 0;
|
|
103
|
+
for (const method of methods) {
|
|
104
|
+
const methodItem = path[method];
|
|
105
|
+
if (!methodItem) continue;
|
|
106
|
+
if (!methodItem.parameters?.length) continue pathLoop;
|
|
107
|
+
++methodCounter;
|
|
108
|
+
methodItem.parameters.forEach((parameter, index, arr) => {
|
|
109
|
+
const uniqueKey = JSON.stringify(parameter);
|
|
110
|
+
parameter = arr[index] = JSON.parse(uniqueKey);
|
|
111
|
+
const handler = () => {
|
|
112
|
+
arr.splice(arr.findIndex((item) => item === parameter), 1);
|
|
113
|
+
if (!arr.length) delete methodItem.parameters;
|
|
114
|
+
};
|
|
115
|
+
parametersHandler[uniqueKey] ||= [];
|
|
116
|
+
parametersHandler[uniqueKey].push(handler);
|
|
117
|
+
});
|
|
118
|
+
}
|
|
119
|
+
if (methodCounter < 2) continue pathLoop;
|
|
120
|
+
Object.entries(parametersHandler).forEach(([uniqueKey, handlers]) => {
|
|
121
|
+
if (handlers.length !== methodCounter) return;
|
|
122
|
+
path.parameters ||= [];
|
|
123
|
+
path.parameters.push(JSON.parse(uniqueKey));
|
|
124
|
+
handlers.forEach((fn) => fn());
|
|
125
|
+
});
|
|
126
|
+
if (path.parameters && !path.parameters.length) delete path.parameters;
|
|
127
|
+
}
|
|
128
|
+
};
|
|
129
|
+
// src/lib/hoist-schema-ref.ts
|
|
130
|
+
/**
|
|
131
|
+
* 识别 schema 上的 `x-ref`,提取到 `components.schemas`,并替换为 `$ref`。
|
|
132
|
+
* 自底向上处理,保证嵌套 object 先变成 `$ref` 再被父级收录。
|
|
133
|
+
*/
|
|
134
|
+
const hoistSchemaRef = (document) => {
|
|
135
|
+
document.components ||= {};
|
|
136
|
+
document.components.schemas ||= {};
|
|
137
|
+
const seen = /* @__PURE__ */ new Map();
|
|
138
|
+
const resolveName = (base, canonical, schema) => {
|
|
139
|
+
let name = base;
|
|
140
|
+
let suffix = 2;
|
|
141
|
+
while (true) {
|
|
142
|
+
const existing = document.components.schemas[name];
|
|
143
|
+
if (!existing) {
|
|
144
|
+
document.components.schemas[name] = schema;
|
|
145
|
+
seen.set(name, canonical);
|
|
146
|
+
return name;
|
|
147
|
+
}
|
|
148
|
+
if ((seen.get(name) ?? JSON.stringify(existing)) === canonical) return name;
|
|
149
|
+
if (name === base) console.warn(`OpenAPI schema component name conflict: "${base}" refers to different schemas, renaming to "${base}-duplicated-${suffix}"`);
|
|
150
|
+
name = `${base}-duplicated-${suffix++}`;
|
|
151
|
+
}
|
|
152
|
+
};
|
|
153
|
+
const visit = (node) => {
|
|
154
|
+
if (!node || typeof node !== "object") return;
|
|
155
|
+
if (Array.isArray(node)) {
|
|
156
|
+
node.forEach(visit);
|
|
157
|
+
return;
|
|
158
|
+
}
|
|
159
|
+
const obj = node;
|
|
160
|
+
for (const value of Object.values(obj)) visit(value);
|
|
161
|
+
const refName = obj["x-ref"];
|
|
162
|
+
if (typeof refName !== "string" || "$ref" in obj) return;
|
|
163
|
+
const { "x-ref": _, ...rest } = obj;
|
|
164
|
+
const cleaned = JSON.parse(JSON.stringify(rest));
|
|
165
|
+
const canonical = JSON.stringify(cleaned);
|
|
166
|
+
const name = resolveName(refName, canonical, cleaned);
|
|
167
|
+
for (const key of Object.keys(obj)) delete obj[key];
|
|
168
|
+
obj["$ref"] = `#/components/schemas/${name}`;
|
|
169
|
+
};
|
|
170
|
+
visit(document.paths);
|
|
171
|
+
if (!Object.keys(document.components.schemas).length) {
|
|
172
|
+
delete document.components.schemas;
|
|
173
|
+
if (!Object.keys(document.components).length) delete document.components;
|
|
174
|
+
}
|
|
114
175
|
};
|
|
115
|
-
|
|
116
176
|
// src/lib/save-to-file.ts
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
177
|
+
const saveToFile = async (document, filename, fileMode) => {
|
|
178
|
+
const dest = path.resolve(filename || "openapi.json");
|
|
179
|
+
const ext = path.extname(dest);
|
|
180
|
+
const content = ext.endsWith(".yaml") || ext.endsWith(".yml") ? YAML.stringify(document) : JSON.stringify(document);
|
|
181
|
+
const size = bytes(Buffer.byteLength(content), { unitSeparator: "" });
|
|
182
|
+
await mkdir(path.dirname(dest), { recursive: true });
|
|
183
|
+
await writeFile(dest, content, {
|
|
184
|
+
mode: fileMode,
|
|
185
|
+
flush: true
|
|
186
|
+
});
|
|
187
|
+
return {
|
|
188
|
+
dest,
|
|
189
|
+
size
|
|
190
|
+
};
|
|
129
191
|
};
|
|
130
|
-
|
|
131
192
|
// src/lib/initialize-document.ts
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
193
|
+
const initializeDocument = async (basic) => {
|
|
194
|
+
const document = JSON.parse(JSON.stringify(basic || {}));
|
|
195
|
+
document.openapi ||= "3.0.3";
|
|
196
|
+
document.tags ||= [];
|
|
197
|
+
document.info ||= {
|
|
198
|
+
title: "",
|
|
199
|
+
version: ""
|
|
200
|
+
};
|
|
201
|
+
document.paths = {};
|
|
202
|
+
document.info.title ||= (await readPackageJson()).name || "OpenAPI";
|
|
203
|
+
document.info.version ||= (await readPackageJson()).version || "0.0.0";
|
|
204
|
+
return document;
|
|
143
205
|
};
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
206
|
+
const readPackageJson = async () => {
|
|
207
|
+
try {
|
|
208
|
+
const content = await readFile(path.resolve("package.json"), "utf8");
|
|
209
|
+
const json = JSON.parse(content);
|
|
210
|
+
return json && typeof json === "object" ? json : {};
|
|
211
|
+
} catch {
|
|
212
|
+
return {};
|
|
213
|
+
}
|
|
152
214
|
};
|
|
153
|
-
|
|
154
|
-
// src/lib/parse-files.ts
|
|
155
|
-
import { getFileValues } from "@aomex/internal-file-import";
|
|
156
|
-
import { Router, WebMiddleware } from "@aomex/web";
|
|
157
|
-
import path3 from "path";
|
|
158
|
-
|
|
159
215
|
// src/lib/method-to-verb.ts
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
216
|
+
const methodToVerb = (method, uri) => {
|
|
217
|
+
method = method.toLowerCase();
|
|
218
|
+
if (method === "get") return uri.includes(":") ? "retrieve" : "list";
|
|
219
|
+
if (method === "post") return "create";
|
|
220
|
+
if (method === "put") return "replace";
|
|
221
|
+
if (method === "patch") return "update";
|
|
222
|
+
return method;
|
|
167
223
|
};
|
|
168
|
-
|
|
169
224
|
// src/lib/parse-files.ts
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
225
|
+
const parseFiles = async (document, files, options = {}) => {
|
|
226
|
+
const mount = options.mount ?? [];
|
|
227
|
+
const envelopeInjector = options.envelope ? createEnvelopeOpenApiInjector(options.envelope) : void 0;
|
|
228
|
+
const usedTags = [];
|
|
229
|
+
const data = [];
|
|
230
|
+
/** 每个 operation 只出现一次,供 envelope 收口与标签补齐 */
|
|
231
|
+
const operations = [];
|
|
232
|
+
for (const file of files) {
|
|
233
|
+
const routers = await getFileValues([file], (item) => !!item && item instanceof Router);
|
|
234
|
+
for (const router of routers) {
|
|
235
|
+
const groupMiddlewareList = router["middlewareList"];
|
|
236
|
+
const builders = router["builders"];
|
|
237
|
+
for (const builder of builders) {
|
|
238
|
+
if (builder.docs.showInOpenapi === false) continue;
|
|
239
|
+
delete builder.docs.showInOpenapi;
|
|
240
|
+
const builderMiddlewareList = mount.concat(groupMiddlewareList).concat(builder["middlewareList"]).filter((middleware) => middleware instanceof WebMiddleware);
|
|
241
|
+
const uri = builder["uri"];
|
|
242
|
+
const pathName = normalizePath(uri);
|
|
243
|
+
const pathItem = document.paths[pathName] ||= {};
|
|
244
|
+
for (const method of builder["methods"]) {
|
|
245
|
+
const methodName = method.toLowerCase();
|
|
246
|
+
const methodItem = pathItem[methodName] = {
|
|
247
|
+
...builder.docs,
|
|
248
|
+
responses: {}
|
|
249
|
+
};
|
|
250
|
+
operations.push({
|
|
251
|
+
pathItem,
|
|
252
|
+
pathName,
|
|
253
|
+
methodItem,
|
|
254
|
+
methodName,
|
|
255
|
+
file,
|
|
256
|
+
uri
|
|
257
|
+
});
|
|
258
|
+
data.push(...builderMiddlewareList.map((item) => {
|
|
259
|
+
return {
|
|
260
|
+
injector: item["openapi"](),
|
|
261
|
+
pathItem,
|
|
262
|
+
pathName,
|
|
263
|
+
methodItem,
|
|
264
|
+
methodName,
|
|
265
|
+
file,
|
|
266
|
+
uri
|
|
267
|
+
};
|
|
268
|
+
}));
|
|
269
|
+
}
|
|
270
|
+
}
|
|
271
|
+
}
|
|
272
|
+
}
|
|
273
|
+
for (const { injector } of data) injector.onDocument?.(document);
|
|
274
|
+
for (const { injector, pathItem, pathName } of data) injector.onPath?.(pathItem, {
|
|
275
|
+
document,
|
|
276
|
+
pathName
|
|
277
|
+
});
|
|
278
|
+
for (const { injector, pathItem, pathName, methodItem, methodName } of data) injector.onMethod?.(methodItem, {
|
|
279
|
+
document,
|
|
280
|
+
pathItem,
|
|
281
|
+
pathName,
|
|
282
|
+
methodName
|
|
283
|
+
});
|
|
284
|
+
for (const { injector, pathItem, pathName, methodItem, methodName } of data) injector.postMethod?.(methodItem, {
|
|
285
|
+
document,
|
|
286
|
+
pathItem,
|
|
287
|
+
pathName,
|
|
288
|
+
methodName
|
|
289
|
+
});
|
|
290
|
+
if (envelopeInjector?.postMethod) for (const { pathItem, pathName, methodItem, methodName } of operations) envelopeInjector.postMethod(methodItem, {
|
|
291
|
+
document,
|
|
292
|
+
pathItem,
|
|
293
|
+
pathName,
|
|
294
|
+
methodName
|
|
295
|
+
});
|
|
296
|
+
for (const { injector, pathItem, pathName } of data) injector.postPath?.(pathItem, {
|
|
297
|
+
document,
|
|
298
|
+
pathName
|
|
299
|
+
});
|
|
300
|
+
for (const { injector } of data) injector.postDocument?.(document);
|
|
301
|
+
for (const { methodItem, methodName, file, uri } of operations) {
|
|
302
|
+
methodItem.tags ||= [getTagByFilename(file)];
|
|
303
|
+
methodItem.operationId ||= snakeCase(methodToVerb(methodName, uri) + " " + uri.replaceAll(":", "_by_"));
|
|
304
|
+
if (methodName === "post") methodItem["x-codegen-request-body-name"] = "body";
|
|
305
|
+
if (!Object.keys(methodItem.responses).length) methodItem.responses = { default: { description: "" } };
|
|
306
|
+
usedTags.push(...methodItem.tags);
|
|
307
|
+
}
|
|
308
|
+
return [...new Set(usedTags)];
|
|
254
309
|
};
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
310
|
+
const normalizePath = (uri) => {
|
|
311
|
+
return uri.replace(/:([a-z0-9_?]+)/gi, (_, $1) => {
|
|
312
|
+
return `{${$1.replace(/[?]/g, "")}}`;
|
|
313
|
+
});
|
|
259
314
|
};
|
|
260
|
-
|
|
261
|
-
|
|
315
|
+
const getTagByFilename = (file) => {
|
|
316
|
+
return path.basename(file).replace(/\..+$/, "");
|
|
262
317
|
};
|
|
263
|
-
|
|
264
318
|
// src/lib/append-tag.ts
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
}
|
|
272
|
-
return undefinedTags;
|
|
319
|
+
const appendTag = (document, usedTags) => {
|
|
320
|
+
const tags = document.tags ||= [];
|
|
321
|
+
const definedTags = tags.map((item) => item.name);
|
|
322
|
+
const undefinedTags = usedTags.filter((tag) => !definedTags.includes(tag)).sort();
|
|
323
|
+
for (const tag of undefinedTags) tags.push({ name: tag });
|
|
324
|
+
return undefinedTags;
|
|
273
325
|
};
|
|
274
|
-
|
|
275
|
-
// src/lib/generate-document-with-spinner.ts
|
|
276
|
-
import { terminal } from "@aomex/console";
|
|
277
|
-
|
|
278
|
-
// src/i18n/index.ts
|
|
279
|
-
import { I18n as I18n3 } from "@aomex/common";
|
|
280
|
-
|
|
281
326
|
// src/i18n/locales/zh-cn.ts
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
327
|
+
const zh = I18n.define({
|
|
328
|
+
initialize: "初始化文档",
|
|
329
|
+
search_routers_files: "搜索路由文件",
|
|
330
|
+
parse_routers: "解析路由",
|
|
331
|
+
add_tag: "添加标签",
|
|
332
|
+
hand_fix_documentation: "手动修复文档",
|
|
333
|
+
optimize_parameter: "优化参数",
|
|
334
|
+
save_to_file: "保存到文件",
|
|
335
|
+
validate: "验证文档",
|
|
336
|
+
help_summary: "OpenAPI v3 文档生成器",
|
|
337
|
+
help_app_listen_tip: "请将 new WebApp 与 app.listen 拆开(或仅在入口 listen),避免 CLI import 时副作用起服",
|
|
338
|
+
has_error: "{{error_count}} 个错误,{{warning_count}} 条警告",
|
|
339
|
+
no_error: "没有错误"
|
|
295
340
|
});
|
|
296
|
-
|
|
297
341
|
// src/i18n/locales/en-us.ts
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
342
|
+
const en = I18n.satisfies(zh).define({
|
|
343
|
+
initialize: "initialize document",
|
|
344
|
+
search_routers_files: "search web routers files",
|
|
345
|
+
parse_routers: "parse routers",
|
|
346
|
+
add_tag: "Add tags",
|
|
347
|
+
hand_fix_documentation: "fix documentation by manual",
|
|
348
|
+
optimize_parameter: "optimize parameters",
|
|
349
|
+
save_to_file: "save to file",
|
|
350
|
+
validate: "validate document",
|
|
351
|
+
help_summary: "OpenAPI v3 documentation generator",
|
|
352
|
+
help_app_listen_tip: "Keep new WebApp separate from app.listen (or listen only in the entry file) so CLI imports do not start the server as a side effect",
|
|
353
|
+
has_error: "{{error_count}} errors, {{warning_count}} warnings",
|
|
354
|
+
no_error: "No errors"
|
|
311
355
|
});
|
|
312
|
-
|
|
313
|
-
// src/i18n/locales/index.ts
|
|
314
|
-
var locales = {
|
|
315
|
-
zh_CN: zh,
|
|
316
|
-
en_US: en
|
|
317
|
-
};
|
|
318
|
-
|
|
319
356
|
// src/i18n/index.ts
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
357
|
+
const i18n = createI18n({
|
|
358
|
+
zh,
|
|
359
|
+
en,
|
|
360
|
+
load: (file) => import(new URL(`./locales/${file}.js`, import.meta.url).href)
|
|
323
361
|
});
|
|
324
|
-
|
|
325
362
|
// src/lib/generate-document-with-spinner.ts
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
}
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
}
|
|
414
|
-
|
|
363
|
+
/**
|
|
364
|
+
* 1. 生成openapi文档
|
|
365
|
+
* 2. 保存文档到文件
|
|
366
|
+
* 3. 验证
|
|
367
|
+
* 4. 控制台输出执行步骤和验证结果
|
|
368
|
+
*
|
|
369
|
+
* 如果是主动调用,则应使用 generateOpenapi()
|
|
370
|
+
* @see generateOpenapi
|
|
371
|
+
*/
|
|
372
|
+
const generateOpenapiWithSpinner = async (config) => {
|
|
373
|
+
const { error, context } = await terminal.runTasks([
|
|
374
|
+
{
|
|
375
|
+
title: i18n.t("initialize"),
|
|
376
|
+
task: async (ctx) => {
|
|
377
|
+
ctx.document = await initializeDocument(config.docs);
|
|
378
|
+
}
|
|
379
|
+
},
|
|
380
|
+
{
|
|
381
|
+
title: i18n.t("search_routers_files"),
|
|
382
|
+
task: async (ctx) => {
|
|
383
|
+
ctx.files = await pathToFiles(config.routers);
|
|
384
|
+
await (0, import_cjs.default)(500);
|
|
385
|
+
}
|
|
386
|
+
},
|
|
387
|
+
{
|
|
388
|
+
title: i18n.t("parse_routers"),
|
|
389
|
+
task: async (ctx) => {
|
|
390
|
+
const app = config.app;
|
|
391
|
+
ctx.usedTags = await parseFiles(ctx.document, ctx.files, {
|
|
392
|
+
mount: app?.["middlewareList"],
|
|
393
|
+
envelope: app?.["options"].envelope
|
|
394
|
+
});
|
|
395
|
+
await (0, import_cjs.default)(500);
|
|
396
|
+
}
|
|
397
|
+
},
|
|
398
|
+
{
|
|
399
|
+
title: i18n.t("add_tag"),
|
|
400
|
+
task: async (ctx, task) => {
|
|
401
|
+
const undefinedTags = appendTag(ctx.document, ctx.usedTags);
|
|
402
|
+
if (undefinedTags.length) task.suffix = terminal.style("gray", undefinedTags.join(","));
|
|
403
|
+
else task.status = "skip";
|
|
404
|
+
}
|
|
405
|
+
},
|
|
406
|
+
{
|
|
407
|
+
title: i18n.t("hand_fix_documentation"),
|
|
408
|
+
skip: !config.fix,
|
|
409
|
+
task: async (ctx) => {
|
|
410
|
+
await config.fix(ctx.document);
|
|
411
|
+
await (0, import_cjs.default)(500);
|
|
412
|
+
}
|
|
413
|
+
},
|
|
414
|
+
{
|
|
415
|
+
title: i18n.t("optimize_parameter"),
|
|
416
|
+
task: async (ctx) => {
|
|
417
|
+
hoistSchemaRef(ctx.document);
|
|
418
|
+
methodParameterToPathParameter(ctx.document);
|
|
419
|
+
await (0, import_cjs.default)(500);
|
|
420
|
+
}
|
|
421
|
+
},
|
|
422
|
+
{
|
|
423
|
+
title: i18n.t("save_to_file"),
|
|
424
|
+
task: async (ctx, task) => {
|
|
425
|
+
const result = await saveToFile(ctx.document, config.saveToFile, config.fileMode);
|
|
426
|
+
task.suffix = terminal.style(["blue", "underline"], path.relative(process.cwd(), result.dest)) + terminal.style("green", ` [${result.size}]`);
|
|
427
|
+
}
|
|
428
|
+
},
|
|
429
|
+
{
|
|
430
|
+
title: i18n.t("validate"),
|
|
431
|
+
task: async (ctx, task) => {
|
|
432
|
+
const result = ctx.validateResult = await validateOpenapi(ctx.document);
|
|
433
|
+
await (0, import_cjs.default)(500);
|
|
434
|
+
if (result.errors.length || result.warnings.length) task.suffix = terminal.style("yellow", i18n.t("has_error", {
|
|
435
|
+
error_count: result.errors.length,
|
|
436
|
+
warning_count: result.warnings.length
|
|
437
|
+
}));
|
|
438
|
+
else task.suffix = terminal.style("green", i18n.t("no_error"));
|
|
439
|
+
}
|
|
440
|
+
}
|
|
441
|
+
]);
|
|
442
|
+
if (error) return null;
|
|
443
|
+
const logSession = terminal.createSession();
|
|
444
|
+
const { errors, warnings } = context.validateResult;
|
|
445
|
+
for (const error of errors) {
|
|
446
|
+
logSession.update(` %error% ${formatValidateMessage(error)}`);
|
|
447
|
+
logSession.commit();
|
|
448
|
+
}
|
|
449
|
+
for (const warning of warnings) {
|
|
450
|
+
logSession.update(` %warning% ${formatValidateMessage(warning)}`);
|
|
451
|
+
logSession.commit();
|
|
452
|
+
}
|
|
453
|
+
return JSON.parse(JSON.stringify(context.document));
|
|
415
454
|
};
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
455
|
+
const formatValidateMessage = (item) => {
|
|
456
|
+
let pathname = item.path.length ? item.path.join(".") : "";
|
|
457
|
+
return `${terminal.style("gray", `[${pathname || "."}]`)} ${item.message}`;
|
|
419
458
|
};
|
|
420
|
-
|
|
421
459
|
// src/openapi.ts
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
460
|
+
/**
|
|
461
|
+
* Console 中间件:生成 OpenAPI 文档。
|
|
462
|
+
*
|
|
463
|
+
* 请把 `new WebApp(...)` 与 `app.listen(...)` 拆开(或仅在入口 listen),
|
|
464
|
+
* 否则 CLI `import` 同一模块会副作用起服、抢端口。
|
|
465
|
+
*
|
|
466
|
+
* ```ts
|
|
467
|
+
* // app.ts
|
|
468
|
+
* export const app = new WebApp({ envelope: { ... }, mount: [...] });
|
|
469
|
+
*
|
|
470
|
+
* // main.ts
|
|
471
|
+
* import { app } from './app.js';
|
|
472
|
+
* app.listen(3000);
|
|
473
|
+
*
|
|
474
|
+
* // console mount
|
|
475
|
+
* openapi({
|
|
476
|
+
* commandName: 'openapi',
|
|
477
|
+
* routers: './src/routers',
|
|
478
|
+
* app, // 与运行时同一实例
|
|
479
|
+
* });
|
|
480
|
+
* ```
|
|
481
|
+
*/
|
|
482
|
+
const openapi = (options) => {
|
|
483
|
+
const { commandName = "openapi" } = options;
|
|
484
|
+
return middleware.console({
|
|
485
|
+
fn: async (ctx, next) => {
|
|
486
|
+
if (ctx.input.command !== commandName) return next();
|
|
487
|
+
ctx.commandMatched = true;
|
|
488
|
+
await generateOpenapiWithSpinner(options);
|
|
489
|
+
},
|
|
490
|
+
help: { onDocument(doc) {
|
|
491
|
+
doc[commandName] = {
|
|
492
|
+
summary: i18n.t("help_summary"),
|
|
493
|
+
description: i18n.t("help_app_listen_tip")
|
|
494
|
+
};
|
|
495
|
+
} }
|
|
496
|
+
});
|
|
436
497
|
};
|
|
437
|
-
|
|
438
498
|
// src/lib/generate-openapi.ts
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
};
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
methodToVerb,
|
|
456
|
-
methods,
|
|
457
|
-
openapi,
|
|
458
|
-
parseFiles,
|
|
459
|
-
saveToFile,
|
|
460
|
-
validateOpenapi
|
|
499
|
+
/**
|
|
500
|
+
* 生成openapi文档
|
|
501
|
+
*/
|
|
502
|
+
const generateOpenapi = async (config) => {
|
|
503
|
+
const document = await initializeDocument(config.docs);
|
|
504
|
+
const files = await pathToFiles(config.routers);
|
|
505
|
+
const app = config.app;
|
|
506
|
+
const usedTags = await parseFiles(document, files, {
|
|
507
|
+
mount: app["middlewareList"],
|
|
508
|
+
envelope: app["options"].envelope
|
|
509
|
+
});
|
|
510
|
+
appendTag(document, usedTags);
|
|
511
|
+
await config.fix?.(document);
|
|
512
|
+
hoistSchemaRef(document);
|
|
513
|
+
methodParameterToPathParameter(document);
|
|
514
|
+
return JSON.parse(JSON.stringify(document));
|
|
461
515
|
};
|
|
516
|
+
export { generateOpenapi, generateOpenapiWithSpinner, hoistSchemaRef, initializeDocument, methodParameterToPathParameter, methodToVerb, methods, openapi, parseFiles, saveToFile, validateOpenapi };
|
|
517
|
+
|
|
462
518
|
//# sourceMappingURL=index.js.map
|