@aomex/openapi 3.30.7 → 3.30.8-alpha.131cf1c.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.d.ts
CHANGED
|
@@ -1,41 +1,65 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import {
|
|
3
|
-
import {
|
|
4
|
-
import {
|
|
5
|
-
|
|
6
|
-
interface GenerateOpenapiOptions {
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
1
|
+
import { OpenAPI } from "@aomex/common";
|
|
2
|
+
import { GlobPathOptions } from "@aomex/internal-file-import";
|
|
3
|
+
import { EnvelopeOptions, WebApp, WebMiddlewareToken } from "@aomex/web";
|
|
4
|
+
import { ConsoleMiddleware } from "@aomex/console";
|
|
5
|
+
import { Mode } from "node:fs";
|
|
6
|
+
export interface GenerateOpenapiOptions {
|
|
7
|
+
/**
|
|
8
|
+
* http接口路由文件
|
|
9
|
+
*/
|
|
10
|
+
routers: GlobPathOptions;
|
|
11
|
+
/**
|
|
12
|
+
* `WebApp` 实例:读取全局 `mount` 与 `envelope`,作为 OpenAPI 注入的单一真源。
|
|
13
|
+
*
|
|
14
|
+
* CLI / 测试会 `import` 该模块时,请把 `new WebApp(...)` 与 `app.listen(...)` 拆开
|
|
15
|
+
*(或仅在入口文件 listen),避免副作用起服。
|
|
16
|
+
*
|
|
17
|
+
* ```ts
|
|
18
|
+
* // app.ts —— 只创建并导出
|
|
19
|
+
* export const app = new WebApp({
|
|
20
|
+
* envelope: { content: { ... } },
|
|
21
|
+
* mount: [formatError({ ... })],
|
|
22
|
+
* // services / logger / ...
|
|
23
|
+
* });
|
|
24
|
+
*
|
|
25
|
+
* // main.ts —— 进程入口才听端口
|
|
26
|
+
* import { app } from './app.js';
|
|
27
|
+
* app.listen(3000);
|
|
28
|
+
*
|
|
29
|
+
* generateOpenapi({
|
|
30
|
+
* routers: './src/routers',
|
|
31
|
+
* app,
|
|
32
|
+
* });
|
|
33
|
+
* ```
|
|
34
|
+
*/
|
|
35
|
+
app?: WebApp;
|
|
36
|
+
/**
|
|
37
|
+
* Openapi基础信息
|
|
38
|
+
*/
|
|
39
|
+
docs?: Omit<OpenAPI.Document, 'paths' | 'openapi' | 'info'> & {
|
|
40
|
+
openapi?: `3.0.${0 | 1 | 2 | 3}`;
|
|
41
|
+
info?: Partial<OpenAPI.Document['info']>;
|
|
42
|
+
};
|
|
43
|
+
/**
|
|
44
|
+
* 手动修复文档内容
|
|
45
|
+
*/
|
|
46
|
+
fix?: (data: OpenAPI.Document) => void | Promise<void>;
|
|
22
47
|
}
|
|
23
48
|
/**
|
|
24
49
|
* 生成openapi文档
|
|
25
50
|
*/
|
|
26
|
-
declare const generateOpenapi: (config: GenerateOpenapiOptions) => Promise<OpenAPI.Document>;
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
fileMode?: Mode;
|
|
51
|
+
export declare const generateOpenapi: (config: GenerateOpenapiOptions) => Promise<OpenAPI.Document>;
|
|
52
|
+
export interface GenerateOpenapiWithSpinnerOptions extends GenerateOpenapiOptions {
|
|
53
|
+
/**
|
|
54
|
+
* 保存到指定文件。默认值:`openapi.json`
|
|
55
|
+
* - `*.json` 保存为JSON格式
|
|
56
|
+
* - `*.yaml` 保存为YAML格式
|
|
57
|
+
*/
|
|
58
|
+
saveToFile?: string;
|
|
59
|
+
/**
|
|
60
|
+
* 设置保存文件的系统权限。
|
|
61
|
+
*/
|
|
62
|
+
fileMode?: Mode;
|
|
39
63
|
}
|
|
40
64
|
/**
|
|
41
65
|
* 1. 生成openapi文档
|
|
@@ -46,42 +70,65 @@ interface GenerateOpenapiWithSpinnerOptions extends GenerateOpenapiOptions {
|
|
|
46
70
|
* 如果是主动调用,则应使用 generateOpenapi()
|
|
47
71
|
* @see generateOpenapi
|
|
48
72
|
*/
|
|
49
|
-
declare const generateOpenapiWithSpinner: (config: GenerateOpenapiWithSpinnerOptions) => Promise<OpenAPI.Document | null>;
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
commandName?: string;
|
|
73
|
+
export declare const generateOpenapiWithSpinner: (config: GenerateOpenapiWithSpinnerOptions) => Promise<OpenAPI.Document | null>;
|
|
74
|
+
export interface OpenapiOptions extends GenerateOpenapiWithSpinnerOptions {
|
|
75
|
+
/**
|
|
76
|
+
* 指令名称。默认值:`openapi`
|
|
77
|
+
*/
|
|
78
|
+
commandName?: string;
|
|
56
79
|
}
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
80
|
+
/**
|
|
81
|
+
* Console 中间件:生成 OpenAPI 文档。
|
|
82
|
+
*
|
|
83
|
+
* 传入 `app` 时请把 `new WebApp(...)` 与 `app.listen(...)` 拆开(或仅在入口 listen),
|
|
84
|
+
* 否则 CLI `import` 同一模块会副作用起服、抢端口。
|
|
85
|
+
*
|
|
86
|
+
* ```ts
|
|
87
|
+
* // app.ts
|
|
88
|
+
* export const app = new WebApp({ envelope: { ... }, mount: [...] });
|
|
89
|
+
*
|
|
90
|
+
* // main.ts
|
|
91
|
+
* import { app } from './app.js';
|
|
92
|
+
* app.listen(3000);
|
|
93
|
+
*
|
|
94
|
+
* // console mount
|
|
95
|
+
* openapi({
|
|
96
|
+
* commandName: 'openapi',
|
|
97
|
+
* routers: './src/routers',
|
|
98
|
+
* app, // 与运行时同一实例
|
|
99
|
+
* });
|
|
100
|
+
* ```
|
|
101
|
+
*/
|
|
102
|
+
export declare const openapi: (options: OpenapiOptions) => ConsoleMiddleware;
|
|
103
|
+
export declare const initializeDocument: (basic?: GenerateOpenapiOptions['docs']) => Promise<OpenAPI.Document<{}>>;
|
|
61
104
|
/**
|
|
62
105
|
* 同一个路径下,所有方法都有相同的parameter时,可以往上提取,这样能减小生成产物
|
|
63
106
|
*/
|
|
64
|
-
declare const methodParameterToPathParameter: (document: OpenAPI.Document) => void;
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
declare const
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
107
|
+
export declare const methodParameterToPathParameter: (document: OpenAPI.Document) => void;
|
|
108
|
+
/**
|
|
109
|
+
* 识别 schema 上的 `x-ref`,提取到 `components.schemas`,并替换为 `$ref`。
|
|
110
|
+
* 自底向上处理,保证嵌套 object 先变成 `$ref` 再被父级收录。
|
|
111
|
+
*/
|
|
112
|
+
export declare const hoistSchemaRef: (document: OpenAPI.Document) => void;
|
|
113
|
+
export declare const methodToVerb: (method: string, uri: string) => string;
|
|
114
|
+
export declare const methods: readonly ['get', 'post', 'put', 'patch', 'delete', 'options', 'head', 'trace'];
|
|
115
|
+
export interface ParseFilesOptions {
|
|
116
|
+
/** 全局中间件(与 `WebApp` 的 `mount` 对应) */
|
|
117
|
+
mount?: WebMiddlewareToken[];
|
|
118
|
+
/** 响应体套壳(与 `WebApp.envelope` 对应);在全部中间件 `postMethod` 之后收口 */
|
|
119
|
+
envelope?: EnvelopeOptions;
|
|
120
|
+
}
|
|
121
|
+
export declare const parseFiles: (document: OpenAPI.Document, files: string[], options?: ParseFilesOptions) => Promise<string[]>;
|
|
122
|
+
export declare const saveToFile: (document: OpenAPI.Document, filename?: string, fileMode?: Mode) => Promise<{
|
|
123
|
+
dest: string;
|
|
124
|
+
size: string;
|
|
75
125
|
}>;
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
message: string;
|
|
126
|
+
export interface OpenapiValidateResultItem {
|
|
127
|
+
path: string[];
|
|
128
|
+
message: string;
|
|
80
129
|
}
|
|
81
|
-
interface OpenapiValidateResult {
|
|
82
|
-
|
|
83
|
-
|
|
130
|
+
export interface OpenapiValidateResult {
|
|
131
|
+
errors: OpenapiValidateResultItem[];
|
|
132
|
+
warnings: OpenapiValidateResultItem[];
|
|
84
133
|
}
|
|
85
|
-
declare const validateOpenapi: (document: OpenAPI.Document) => Promise<OpenapiValidateResult>;
|
|
86
|
-
|
|
87
|
-
export { type GenerateOpenapiOptions, type GenerateOpenapiWithSpinnerOptions, type OpenapiOptions, type OpenapiValidateResult, type OpenapiValidateResultItem, generateOpenapi, generateOpenapiWithSpinner, initializeDocument, methodParameterToPathParameter, methodToVerb, methods, openapi, parseFiles, saveToFile, validateOpenapi };
|
|
134
|
+
export declare const validateOpenapi: (document: OpenAPI.Document) => Promise<OpenapiValidateResult>;
|