@navios/openapi 0.7.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/LICENSE +8 -0
- package/README.md +260 -0
- package/dist/src/__tests__/decorators.spec.d.mts +2 -0
- package/dist/src/__tests__/decorators.spec.d.mts.map +1 -0
- package/dist/src/__tests__/metadata.spec.d.mts +2 -0
- package/dist/src/__tests__/metadata.spec.d.mts.map +1 -0
- package/dist/src/__tests__/services.spec.d.mts +2 -0
- package/dist/src/__tests__/services.spec.d.mts.map +1 -0
- package/dist/src/decorators/api-deprecated.decorator.d.mts +33 -0
- package/dist/src/decorators/api-deprecated.decorator.d.mts.map +1 -0
- package/dist/src/decorators/api-exclude.decorator.d.mts +26 -0
- package/dist/src/decorators/api-exclude.decorator.d.mts.map +1 -0
- package/dist/src/decorators/api-operation.decorator.d.mts +58 -0
- package/dist/src/decorators/api-operation.decorator.d.mts.map +1 -0
- package/dist/src/decorators/api-security.decorator.d.mts +36 -0
- package/dist/src/decorators/api-security.decorator.d.mts.map +1 -0
- package/dist/src/decorators/api-stream.decorator.d.mts +50 -0
- package/dist/src/decorators/api-stream.decorator.d.mts.map +1 -0
- package/dist/src/decorators/api-summary.decorator.d.mts +24 -0
- package/dist/src/decorators/api-summary.decorator.d.mts.map +1 -0
- package/dist/src/decorators/api-tag.decorator.d.mts +42 -0
- package/dist/src/decorators/api-tag.decorator.d.mts.map +1 -0
- package/dist/src/decorators/index.d.mts +8 -0
- package/dist/src/decorators/index.d.mts.map +1 -0
- package/dist/src/index.d.mts +5 -0
- package/dist/src/index.d.mts.map +1 -0
- package/dist/src/metadata/index.d.mts +2 -0
- package/dist/src/metadata/index.d.mts.map +1 -0
- package/dist/src/metadata/openapi.metadata.d.mts +30 -0
- package/dist/src/metadata/openapi.metadata.d.mts.map +1 -0
- package/dist/src/services/endpoint-scanner.service.d.mts +42 -0
- package/dist/src/services/endpoint-scanner.service.d.mts.map +1 -0
- package/dist/src/services/index.d.mts +6 -0
- package/dist/src/services/index.d.mts.map +1 -0
- package/dist/src/services/metadata-extractor.service.d.mts +19 -0
- package/dist/src/services/metadata-extractor.service.d.mts.map +1 -0
- package/dist/src/services/openapi-generator.service.d.mts +91 -0
- package/dist/src/services/openapi-generator.service.d.mts.map +1 -0
- package/dist/src/services/path-builder.service.d.mts +73 -0
- package/dist/src/services/path-builder.service.d.mts.map +1 -0
- package/dist/src/services/schema-converter.service.d.mts +57 -0
- package/dist/src/services/schema-converter.service.d.mts.map +1 -0
- package/dist/src/tokens/index.d.mts +18 -0
- package/dist/src/tokens/index.d.mts.map +1 -0
- package/dist/tsconfig.lib.tsbuildinfo +1 -0
- package/dist/tsconfig.spec.tsbuildinfo +1 -0
- package/dist/tsconfig.tsbuildinfo +1 -0
- package/dist/tsdown.config.d.mts +3 -0
- package/dist/tsdown.config.d.mts.map +1 -0
- package/dist/vitest.config.d.mts +3 -0
- package/dist/vitest.config.d.mts.map +1 -0
- package/lib/index.cjs +2120 -0
- package/lib/index.cjs.map +1 -0
- package/lib/index.d.cts +594 -0
- package/lib/index.d.cts.map +1 -0
- package/lib/index.d.mts +594 -0
- package/lib/index.d.mts.map +1 -0
- package/lib/index.mjs +2077 -0
- package/lib/index.mjs.map +1 -0
- package/package.json +44 -0
- package/project.json +66 -0
- package/src/__tests__/decorators.spec.mts +185 -0
- package/src/__tests__/metadata.spec.mts +207 -0
- package/src/__tests__/services.spec.mts +216 -0
- package/src/decorators/api-deprecated.decorator.mts +45 -0
- package/src/decorators/api-exclude.decorator.mts +29 -0
- package/src/decorators/api-operation.decorator.mts +59 -0
- package/src/decorators/api-security.decorator.mts +44 -0
- package/src/decorators/api-stream.decorator.mts +55 -0
- package/src/decorators/api-summary.decorator.mts +33 -0
- package/src/decorators/api-tag.decorator.mts +51 -0
- package/src/decorators/index.mts +7 -0
- package/src/index.mts +42 -0
- package/src/metadata/index.mts +2 -0
- package/src/metadata/openapi.metadata.mts +30 -0
- package/src/services/endpoint-scanner.service.mts +118 -0
- package/src/services/index.mts +21 -0
- package/src/services/metadata-extractor.service.mts +91 -0
- package/src/services/openapi-generator.service.mts +219 -0
- package/src/services/path-builder.service.mts +344 -0
- package/src/services/schema-converter.service.mts +96 -0
- package/src/tokens/index.mts +24 -0
- package/tsconfig.json +24 -0
- package/tsconfig.lib.json +8 -0
- package/tsconfig.spec.json +12 -0
- package/tsdown.config.mts +35 -0
- package/vitest.config.mts +11 -0
package/lib/index.d.mts
ADDED
|
@@ -0,0 +1,594 @@
|
|
|
1
|
+
import * as _navios_core0 from "@navios/core";
|
|
2
|
+
import { ControllerMetadata, HandlerMetadata, ModuleMetadata } from "@navios/core";
|
|
3
|
+
import { ZodType, z } from "zod/v4";
|
|
4
|
+
import { oas31 } from "zod-openapi";
|
|
5
|
+
import { BaseEndpointConfig } from "@navios/builder";
|
|
6
|
+
|
|
7
|
+
//#region src/decorators/api-tag.decorator.d.mts
|
|
8
|
+
declare const ApiTagSchema: z.ZodObject<{
|
|
9
|
+
name: z.ZodString;
|
|
10
|
+
description: z.ZodOptional<z.ZodString>;
|
|
11
|
+
}, z.core.$strip>;
|
|
12
|
+
/** Options for the @ApiTag decorator, inferred from the schema */
|
|
13
|
+
type ApiTagOptions = z.infer<typeof ApiTagSchema>;
|
|
14
|
+
/**
|
|
15
|
+
* Groups endpoints under a specific tag/folder in the documentation.
|
|
16
|
+
*
|
|
17
|
+
* Can be applied to controllers (affects all endpoints) or individual methods.
|
|
18
|
+
* When applied to both, the method-level tag takes precedence.
|
|
19
|
+
*
|
|
20
|
+
* @param name - The tag name
|
|
21
|
+
* @param description - Optional tag description
|
|
22
|
+
*
|
|
23
|
+
* @example
|
|
24
|
+
* ```typescript
|
|
25
|
+
* // Apply to entire controller
|
|
26
|
+
* @Controller()
|
|
27
|
+
* @ApiTag('Users', 'User management operations')
|
|
28
|
+
* export class UserController {
|
|
29
|
+
* @Endpoint(getUser)
|
|
30
|
+
* async getUser() {}
|
|
31
|
+
* }
|
|
32
|
+
*
|
|
33
|
+
* // Apply to individual endpoint
|
|
34
|
+
* @Controller()
|
|
35
|
+
* export class MixedController {
|
|
36
|
+
* @Endpoint(getUser)
|
|
37
|
+
* @ApiTag('Users')
|
|
38
|
+
* async getUser() {}
|
|
39
|
+
*
|
|
40
|
+
* @Endpoint(getOrder)
|
|
41
|
+
* @ApiTag('Orders')
|
|
42
|
+
* async getOrder() {}
|
|
43
|
+
* }
|
|
44
|
+
* ```
|
|
45
|
+
*/
|
|
46
|
+
declare function ApiTag(name: string, description?: string): <T>(target: T, context: ClassDecoratorContext | ClassMethodDecoratorContext) => T;
|
|
47
|
+
//#endregion
|
|
48
|
+
//#region src/decorators/api-operation.decorator.d.mts
|
|
49
|
+
declare const ApiOperationSchema: z.ZodObject<{
|
|
50
|
+
summary: z.ZodOptional<z.ZodString>;
|
|
51
|
+
description: z.ZodOptional<z.ZodString>;
|
|
52
|
+
operationId: z.ZodOptional<z.ZodString>;
|
|
53
|
+
deprecated: z.ZodOptional<z.ZodBoolean>;
|
|
54
|
+
externalDocs: z.ZodOptional<z.ZodObject<{
|
|
55
|
+
url: z.ZodString;
|
|
56
|
+
description: z.ZodOptional<z.ZodString>;
|
|
57
|
+
}, z.core.$strip>>;
|
|
58
|
+
}, z.core.$strip>;
|
|
59
|
+
/** Options for the @ApiOperation decorator, inferred from the schema */
|
|
60
|
+
type ApiOperationOptions = z.infer<typeof ApiOperationSchema>;
|
|
61
|
+
/**
|
|
62
|
+
* Provides detailed operation metadata for an endpoint.
|
|
63
|
+
*
|
|
64
|
+
* Use this decorator when you need to specify multiple operation properties.
|
|
65
|
+
* For simple cases, consider using @ApiSummary instead.
|
|
66
|
+
*
|
|
67
|
+
* @param options - Operation configuration options
|
|
68
|
+
*
|
|
69
|
+
* @example
|
|
70
|
+
* ```typescript
|
|
71
|
+
* @Controller()
|
|
72
|
+
* export class UserController {
|
|
73
|
+
* @Endpoint(getUser)
|
|
74
|
+
* @ApiOperation({
|
|
75
|
+
* summary: 'Get user by ID',
|
|
76
|
+
* description: 'Retrieves a user by their unique identifier. Returns 404 if not found.',
|
|
77
|
+
* operationId: 'getUserById',
|
|
78
|
+
* })
|
|
79
|
+
* async getUser(params: EndpointParams<typeof getUser>) {}
|
|
80
|
+
*
|
|
81
|
+
* @Endpoint(legacyGetUser)
|
|
82
|
+
* @ApiOperation({
|
|
83
|
+
* summary: 'Get user (legacy)',
|
|
84
|
+
* deprecated: true,
|
|
85
|
+
* externalDocs: {
|
|
86
|
+
* url: 'https://docs.example.com/migration',
|
|
87
|
+
* description: 'Migration guide'
|
|
88
|
+
* }
|
|
89
|
+
* })
|
|
90
|
+
* async getLegacyUser() {}
|
|
91
|
+
* }
|
|
92
|
+
* ```
|
|
93
|
+
*/
|
|
94
|
+
declare const ApiOperation: _navios_core0.ClassSchemaAttribute<z.ZodObject<{
|
|
95
|
+
summary: z.ZodOptional<z.ZodString>;
|
|
96
|
+
description: z.ZodOptional<z.ZodString>;
|
|
97
|
+
operationId: z.ZodOptional<z.ZodString>;
|
|
98
|
+
deprecated: z.ZodOptional<z.ZodBoolean>;
|
|
99
|
+
externalDocs: z.ZodOptional<z.ZodObject<{
|
|
100
|
+
url: z.ZodString;
|
|
101
|
+
description: z.ZodOptional<z.ZodString>;
|
|
102
|
+
}, z.core.$strip>>;
|
|
103
|
+
}, z.core.$strip>>;
|
|
104
|
+
//#endregion
|
|
105
|
+
//#region src/decorators/api-summary.decorator.d.mts
|
|
106
|
+
/**
|
|
107
|
+
* Shorthand decorator for adding just a summary to an endpoint.
|
|
108
|
+
*
|
|
109
|
+
* This is equivalent to `@ApiOperation({ summary: '...' })` but more concise.
|
|
110
|
+
*
|
|
111
|
+
* @param summary - Short summary text for the endpoint
|
|
112
|
+
*
|
|
113
|
+
* @example
|
|
114
|
+
* ```typescript
|
|
115
|
+
* @Controller()
|
|
116
|
+
* export class UserController {
|
|
117
|
+
* @Endpoint(getUser)
|
|
118
|
+
* @ApiSummary('Get user by ID')
|
|
119
|
+
* async getUser() {}
|
|
120
|
+
*
|
|
121
|
+
* @Endpoint(createUser)
|
|
122
|
+
* @ApiSummary('Create a new user')
|
|
123
|
+
* async createUser() {}
|
|
124
|
+
* }
|
|
125
|
+
* ```
|
|
126
|
+
*/
|
|
127
|
+
declare const ApiSummary: _navios_core0.ClassSchemaAttribute<z.ZodString>;
|
|
128
|
+
//#endregion
|
|
129
|
+
//#region src/decorators/api-deprecated.decorator.d.mts
|
|
130
|
+
declare const ApiDeprecatedSchema: z.ZodObject<{
|
|
131
|
+
message: z.ZodOptional<z.ZodString>;
|
|
132
|
+
}, z.core.$strip>;
|
|
133
|
+
/** Options for the @ApiDeprecated decorator, inferred from the schema */
|
|
134
|
+
type ApiDeprecatedOptions = z.infer<typeof ApiDeprecatedSchema>;
|
|
135
|
+
/**
|
|
136
|
+
* Marks an endpoint as deprecated.
|
|
137
|
+
*
|
|
138
|
+
* Deprecated endpoints are shown with a visual indicator in documentation
|
|
139
|
+
* and may include a migration message.
|
|
140
|
+
*
|
|
141
|
+
* @param message - Optional deprecation message
|
|
142
|
+
*
|
|
143
|
+
* @example
|
|
144
|
+
* ```typescript
|
|
145
|
+
* @Controller()
|
|
146
|
+
* export class UserController {
|
|
147
|
+
* // Simple deprecation
|
|
148
|
+
* @Endpoint(legacyGetUser)
|
|
149
|
+
* @ApiDeprecated()
|
|
150
|
+
* async getLegacyUser() {}
|
|
151
|
+
*
|
|
152
|
+
* // With migration message
|
|
153
|
+
* @Endpoint(oldCreateUser)
|
|
154
|
+
* @ApiDeprecated('Use POST /v2/users instead')
|
|
155
|
+
* async oldCreateUser() {}
|
|
156
|
+
* }
|
|
157
|
+
* ```
|
|
158
|
+
*/
|
|
159
|
+
declare function ApiDeprecated(message?: string): <T>(target: T, context: ClassDecoratorContext | ClassMethodDecoratorContext) => T;
|
|
160
|
+
//#endregion
|
|
161
|
+
//#region src/decorators/api-security.decorator.d.mts
|
|
162
|
+
declare const ApiSecuritySchema: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
|
|
163
|
+
/** Security requirement for an endpoint, inferred from the schema */
|
|
164
|
+
type ApiSecurityRequirement = z.infer<typeof ApiSecuritySchema>;
|
|
165
|
+
/**
|
|
166
|
+
* Specifies security requirements for an endpoint.
|
|
167
|
+
*
|
|
168
|
+
* The security requirement object maps security scheme names to their scopes.
|
|
169
|
+
* For schemes that don't use scopes (like API keys), use an empty array.
|
|
170
|
+
*
|
|
171
|
+
* @param requirements - Security requirements object
|
|
172
|
+
*
|
|
173
|
+
* @example
|
|
174
|
+
* ```typescript
|
|
175
|
+
* @Controller()
|
|
176
|
+
* export class UserController {
|
|
177
|
+
* // Require bearer token authentication
|
|
178
|
+
* @Endpoint(getUser)
|
|
179
|
+
* @ApiSecurity({ bearerAuth: [] })
|
|
180
|
+
* async getUser() {}
|
|
181
|
+
*
|
|
182
|
+
* // Require multiple authentication methods
|
|
183
|
+
* @Endpoint(adminEndpoint)
|
|
184
|
+
* @ApiSecurity({ bearerAuth: [], apiKey: [] })
|
|
185
|
+
* async adminAction() {}
|
|
186
|
+
*
|
|
187
|
+
* // OAuth2 with specific scopes
|
|
188
|
+
* @Endpoint(writeUser)
|
|
189
|
+
* @ApiSecurity({ oauth2: ['users:write', 'users:read'] })
|
|
190
|
+
* async writeUser() {}
|
|
191
|
+
* }
|
|
192
|
+
* ```
|
|
193
|
+
*/
|
|
194
|
+
declare const ApiSecurity: _navios_core0.ClassSchemaAttribute<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
|
|
195
|
+
//#endregion
|
|
196
|
+
//#region src/decorators/api-exclude.decorator.d.mts
|
|
197
|
+
/**
|
|
198
|
+
* Excludes an endpoint from OpenAPI documentation.
|
|
199
|
+
*
|
|
200
|
+
* Use this decorator for internal endpoints that should not be visible
|
|
201
|
+
* in the public API documentation.
|
|
202
|
+
*
|
|
203
|
+
* @example
|
|
204
|
+
* ```typescript
|
|
205
|
+
* @Controller()
|
|
206
|
+
* export class HealthController {
|
|
207
|
+
* @Endpoint(healthCheck)
|
|
208
|
+
* @ApiExclude()
|
|
209
|
+
* async healthCheck() {
|
|
210
|
+
* return { status: 'ok' }
|
|
211
|
+
* }
|
|
212
|
+
*
|
|
213
|
+
* @Endpoint(internalMetrics)
|
|
214
|
+
* @ApiExclude()
|
|
215
|
+
* async internalMetrics() {
|
|
216
|
+
* return { ... }
|
|
217
|
+
* }
|
|
218
|
+
* }
|
|
219
|
+
* ```
|
|
220
|
+
*/
|
|
221
|
+
declare const ApiExclude: _navios_core0.ClassAttribute;
|
|
222
|
+
//#endregion
|
|
223
|
+
//#region src/decorators/api-stream.decorator.d.mts
|
|
224
|
+
declare const ApiStreamSchema: z.ZodObject<{
|
|
225
|
+
contentType: z.ZodString;
|
|
226
|
+
description: z.ZodOptional<z.ZodString>;
|
|
227
|
+
}, z.core.$strip>;
|
|
228
|
+
/** Options for the @ApiStream decorator, inferred from the schema */
|
|
229
|
+
type ApiStreamOptions = z.infer<typeof ApiStreamSchema>;
|
|
230
|
+
/**
|
|
231
|
+
* Specifies content type and description for stream endpoints.
|
|
232
|
+
*
|
|
233
|
+
* Stream endpoints don't have a responseSchema, so this decorator provides
|
|
234
|
+
* the necessary metadata for OpenAPI documentation.
|
|
235
|
+
*
|
|
236
|
+
* @param options - Stream response options
|
|
237
|
+
*
|
|
238
|
+
* @example
|
|
239
|
+
* ```typescript
|
|
240
|
+
* @Controller()
|
|
241
|
+
* export class FileController {
|
|
242
|
+
* // Binary file download
|
|
243
|
+
* @Stream(downloadFile)
|
|
244
|
+
* @ApiStream({
|
|
245
|
+
* contentType: 'application/octet-stream',
|
|
246
|
+
* description: 'Download file as binary stream'
|
|
247
|
+
* })
|
|
248
|
+
* async download(params: StreamParams<typeof downloadFile>, reply: Reply) {
|
|
249
|
+
* // Stream implementation
|
|
250
|
+
* }
|
|
251
|
+
* }
|
|
252
|
+
*
|
|
253
|
+
* @Controller()
|
|
254
|
+
* export class EventController {
|
|
255
|
+
* // Server-Sent Events
|
|
256
|
+
* @Stream(streamEvents)
|
|
257
|
+
* @ApiStream({
|
|
258
|
+
* contentType: 'text/event-stream',
|
|
259
|
+
* description: 'Real-time event stream'
|
|
260
|
+
* })
|
|
261
|
+
* async stream(params: StreamParams<typeof streamEvents>, reply: Reply) {
|
|
262
|
+
* // SSE implementation
|
|
263
|
+
* }
|
|
264
|
+
* }
|
|
265
|
+
* ```
|
|
266
|
+
*/
|
|
267
|
+
declare const ApiStream: _navios_core0.ClassSchemaAttribute<z.ZodObject<{
|
|
268
|
+
contentType: z.ZodString;
|
|
269
|
+
description: z.ZodOptional<z.ZodString>;
|
|
270
|
+
}, z.core.$strip>>;
|
|
271
|
+
//#endregion
|
|
272
|
+
//#region src/metadata/openapi.metadata.d.mts
|
|
273
|
+
/**
|
|
274
|
+
* Extracted OpenAPI metadata for an endpoint
|
|
275
|
+
*/
|
|
276
|
+
interface OpenApiEndpointMetadata {
|
|
277
|
+
/** Tags for grouping endpoints */
|
|
278
|
+
tags: string[];
|
|
279
|
+
/** Short summary */
|
|
280
|
+
summary?: string;
|
|
281
|
+
/** Detailed description */
|
|
282
|
+
description?: string;
|
|
283
|
+
/** Unique operation identifier */
|
|
284
|
+
operationId?: string;
|
|
285
|
+
/** Whether the endpoint is deprecated */
|
|
286
|
+
deprecated: boolean;
|
|
287
|
+
/** Deprecation message */
|
|
288
|
+
deprecationMessage?: string;
|
|
289
|
+
/** Security requirements */
|
|
290
|
+
security?: ApiSecurityRequirement[];
|
|
291
|
+
/** External documentation link */
|
|
292
|
+
externalDocs?: {
|
|
293
|
+
url: string;
|
|
294
|
+
description?: string;
|
|
295
|
+
};
|
|
296
|
+
/** Stream content type (for stream endpoints) */
|
|
297
|
+
stream?: ApiStreamOptions;
|
|
298
|
+
/** Whether to exclude from documentation */
|
|
299
|
+
excluded: boolean;
|
|
300
|
+
}
|
|
301
|
+
//#endregion
|
|
302
|
+
//#region src/services/endpoint-scanner.service.d.mts
|
|
303
|
+
/**
|
|
304
|
+
* Represents a discovered endpoint with all its metadata
|
|
305
|
+
*/
|
|
306
|
+
interface DiscoveredEndpoint {
|
|
307
|
+
/** Module metadata */
|
|
308
|
+
module: ModuleMetadata;
|
|
309
|
+
/** Controller class */
|
|
310
|
+
controllerClass: any;
|
|
311
|
+
/** Controller metadata */
|
|
312
|
+
controller: ControllerMetadata;
|
|
313
|
+
/** Handler (endpoint) metadata */
|
|
314
|
+
handler: HandlerMetadata<any>;
|
|
315
|
+
/** Endpoint configuration from @navios/builder */
|
|
316
|
+
config: BaseEndpointConfig;
|
|
317
|
+
/** Extracted OpenAPI metadata */
|
|
318
|
+
openApiMetadata: OpenApiEndpointMetadata;
|
|
319
|
+
}
|
|
320
|
+
/**
|
|
321
|
+
* Service responsible for scanning modules and discovering endpoints.
|
|
322
|
+
*
|
|
323
|
+
* Iterates through all modules, controllers, and endpoints,
|
|
324
|
+
* extracting OpenAPI metadata from decorators.
|
|
325
|
+
*/
|
|
326
|
+
declare class EndpointScannerService {
|
|
327
|
+
private readonly logger;
|
|
328
|
+
private readonly metadataExtractor;
|
|
329
|
+
/**
|
|
330
|
+
* Scans all loaded modules and discovers endpoints.
|
|
331
|
+
*
|
|
332
|
+
* @param modules - Map of loaded modules from NaviosApplication
|
|
333
|
+
* @returns Array of discovered endpoints
|
|
334
|
+
*/
|
|
335
|
+
scan(modules: Map<string, ModuleMetadata>): DiscoveredEndpoint[];
|
|
336
|
+
/**
|
|
337
|
+
* Scans a controller and returns its endpoints
|
|
338
|
+
*/
|
|
339
|
+
private scanController;
|
|
340
|
+
}
|
|
341
|
+
//#endregion
|
|
342
|
+
//#region src/services/metadata-extractor.service.d.mts
|
|
343
|
+
/**
|
|
344
|
+
* Service responsible for extracting OpenAPI metadata from decorators.
|
|
345
|
+
*
|
|
346
|
+
* Merges controller-level and handler-level metadata to produce
|
|
347
|
+
* a complete OpenAPI metadata object for each endpoint.
|
|
348
|
+
*/
|
|
349
|
+
declare class MetadataExtractorService {
|
|
350
|
+
/**
|
|
351
|
+
* Extracts and merges OpenAPI metadata from controller and handler.
|
|
352
|
+
*
|
|
353
|
+
* @param controller - Controller metadata
|
|
354
|
+
* @param handler - Handler metadata
|
|
355
|
+
* @returns Merged OpenAPI metadata
|
|
356
|
+
*/
|
|
357
|
+
extract(controller: ControllerMetadata, handler: HandlerMetadata<any>): OpenApiEndpointMetadata;
|
|
358
|
+
}
|
|
359
|
+
//#endregion
|
|
360
|
+
//#region src/services/schema-converter.service.d.mts
|
|
361
|
+
type SchemaObject = oas31.SchemaObject;
|
|
362
|
+
type ReferenceObject = oas31.ReferenceObject;
|
|
363
|
+
/**
|
|
364
|
+
* Result of schema conversion
|
|
365
|
+
*/
|
|
366
|
+
interface SchemaConversionResult {
|
|
367
|
+
schema: SchemaObject | ReferenceObject;
|
|
368
|
+
components: Record<string, SchemaObject>;
|
|
369
|
+
}
|
|
370
|
+
/**
|
|
371
|
+
* Service responsible for converting Zod schemas to OpenAPI schemas.
|
|
372
|
+
*
|
|
373
|
+
* Uses zod-openapi library which supports Zod 4's native `.meta()` method
|
|
374
|
+
* for OpenAPI-specific metadata.
|
|
375
|
+
*/
|
|
376
|
+
declare class SchemaConverterService {
|
|
377
|
+
/**
|
|
378
|
+
* Converts a Zod schema to an OpenAPI schema object.
|
|
379
|
+
*
|
|
380
|
+
* @param schema - Zod schema to convert
|
|
381
|
+
* @returns OpenAPI schema object with any component schemas
|
|
382
|
+
*
|
|
383
|
+
* @example
|
|
384
|
+
* ```typescript
|
|
385
|
+
* const userSchema = z.object({
|
|
386
|
+
* id: z.string().meta({ openapi: { example: 'usr_123' } }),
|
|
387
|
+
* name: z.string(),
|
|
388
|
+
* })
|
|
389
|
+
*
|
|
390
|
+
* const result = schemaConverter.convert(userSchema)
|
|
391
|
+
* // { schema: { type: 'object', properties: { ... } }, components: {} }
|
|
392
|
+
* ```
|
|
393
|
+
*/
|
|
394
|
+
convert(schema: ZodType): SchemaConversionResult;
|
|
395
|
+
/**
|
|
396
|
+
* Checks if a schema property represents a File type.
|
|
397
|
+
*
|
|
398
|
+
* Used for multipart form handling to convert File types to binary format.
|
|
399
|
+
*
|
|
400
|
+
* @param schema - Schema object to check
|
|
401
|
+
* @returns true if the schema represents a file
|
|
402
|
+
*/
|
|
403
|
+
isFileSchema(schema: SchemaObject): boolean;
|
|
404
|
+
/**
|
|
405
|
+
* Transforms schema properties to handle File/Blob types for multipart.
|
|
406
|
+
*
|
|
407
|
+
* Converts File types to OpenAPI binary format and handles arrays of files.
|
|
408
|
+
*
|
|
409
|
+
* @param properties - Schema properties object
|
|
410
|
+
* @returns Transformed properties with file types as binary
|
|
411
|
+
*/
|
|
412
|
+
transformFileProperties(properties: Record<string, SchemaObject>): Record<string, SchemaObject>;
|
|
413
|
+
}
|
|
414
|
+
//#endregion
|
|
415
|
+
//#region src/services/path-builder.service.d.mts
|
|
416
|
+
type PathItemObject = oas31.PathItemObject;
|
|
417
|
+
/**
|
|
418
|
+
* Result of path item generation
|
|
419
|
+
*/
|
|
420
|
+
interface PathItemResult {
|
|
421
|
+
path: string;
|
|
422
|
+
pathItem: PathItemObject;
|
|
423
|
+
}
|
|
424
|
+
/**
|
|
425
|
+
* Service responsible for building OpenAPI path items from endpoints.
|
|
426
|
+
*
|
|
427
|
+
* Handles URL parameter conversion, request body generation,
|
|
428
|
+
* and response schema generation for different endpoint types.
|
|
429
|
+
*/
|
|
430
|
+
declare class PathBuilderService {
|
|
431
|
+
private readonly schemaConverter;
|
|
432
|
+
/**
|
|
433
|
+
* Generates an OpenAPI path item for a discovered endpoint.
|
|
434
|
+
*
|
|
435
|
+
* @param endpoint - Discovered endpoint with metadata
|
|
436
|
+
* @returns Path string and path item object
|
|
437
|
+
*/
|
|
438
|
+
build(endpoint: DiscoveredEndpoint): PathItemResult;
|
|
439
|
+
/**
|
|
440
|
+
* Converts Navios URL param format ($param) to OpenAPI format ({param})
|
|
441
|
+
*/
|
|
442
|
+
convertUrlParams(url: string): string;
|
|
443
|
+
/**
|
|
444
|
+
* Extracts URL parameter names from a URL pattern
|
|
445
|
+
*/
|
|
446
|
+
extractUrlParamNames(url: string): string[];
|
|
447
|
+
/**
|
|
448
|
+
* Gets the endpoint type based on the adapter token
|
|
449
|
+
*/
|
|
450
|
+
getEndpointType(handler: HandlerMetadata<any>): 'endpoint' | 'multipart' | 'stream';
|
|
451
|
+
/**
|
|
452
|
+
* Builds OpenAPI parameters from endpoint config
|
|
453
|
+
*/
|
|
454
|
+
private buildParameters;
|
|
455
|
+
/**
|
|
456
|
+
* Builds request body based on endpoint type
|
|
457
|
+
*/
|
|
458
|
+
private buildRequestBody;
|
|
459
|
+
/**
|
|
460
|
+
* Builds request body for JSON endpoints
|
|
461
|
+
*/
|
|
462
|
+
private buildJsonRequestBody;
|
|
463
|
+
/**
|
|
464
|
+
* Builds request body for multipart endpoints
|
|
465
|
+
*/
|
|
466
|
+
private buildMultipartRequestBody;
|
|
467
|
+
/**
|
|
468
|
+
* Builds responses based on endpoint type
|
|
469
|
+
*/
|
|
470
|
+
private buildResponses;
|
|
471
|
+
/**
|
|
472
|
+
* Builds responses for JSON endpoints
|
|
473
|
+
*/
|
|
474
|
+
private buildJsonResponses;
|
|
475
|
+
/**
|
|
476
|
+
* Builds responses for stream endpoints
|
|
477
|
+
*/
|
|
478
|
+
private buildStreamResponses;
|
|
479
|
+
/**
|
|
480
|
+
* Gets content object for different stream types
|
|
481
|
+
*/
|
|
482
|
+
private getStreamContent;
|
|
483
|
+
}
|
|
484
|
+
//#endregion
|
|
485
|
+
//#region src/services/openapi-generator.service.d.mts
|
|
486
|
+
type OpenAPIObject = oas31.OpenAPIObject;
|
|
487
|
+
type SecuritySchemeObject = oas31.SecuritySchemeObject;
|
|
488
|
+
type TagObject = oas31.TagObject;
|
|
489
|
+
/**
|
|
490
|
+
* Options for generating the OpenAPI document
|
|
491
|
+
*/
|
|
492
|
+
interface OpenApiGeneratorOptions {
|
|
493
|
+
/**
|
|
494
|
+
* OpenAPI document info
|
|
495
|
+
*/
|
|
496
|
+
info: {
|
|
497
|
+
title: string;
|
|
498
|
+
version: string;
|
|
499
|
+
description?: string;
|
|
500
|
+
termsOfService?: string;
|
|
501
|
+
contact?: {
|
|
502
|
+
name?: string;
|
|
503
|
+
url?: string;
|
|
504
|
+
email?: string;
|
|
505
|
+
};
|
|
506
|
+
license?: {
|
|
507
|
+
name: string;
|
|
508
|
+
url?: string;
|
|
509
|
+
};
|
|
510
|
+
};
|
|
511
|
+
/**
|
|
512
|
+
* External documentation
|
|
513
|
+
*/
|
|
514
|
+
externalDocs?: {
|
|
515
|
+
url: string;
|
|
516
|
+
description?: string;
|
|
517
|
+
};
|
|
518
|
+
/**
|
|
519
|
+
* Server definitions
|
|
520
|
+
*/
|
|
521
|
+
servers?: Array<{
|
|
522
|
+
url: string;
|
|
523
|
+
description?: string;
|
|
524
|
+
variables?: Record<string, {
|
|
525
|
+
default: string;
|
|
526
|
+
enum?: string[];
|
|
527
|
+
description?: string;
|
|
528
|
+
}>;
|
|
529
|
+
}>;
|
|
530
|
+
/**
|
|
531
|
+
* Security scheme definitions
|
|
532
|
+
*/
|
|
533
|
+
securitySchemes?: Record<string, SecuritySchemeObject>;
|
|
534
|
+
/**
|
|
535
|
+
* Global security requirements
|
|
536
|
+
*/
|
|
537
|
+
security?: Array<Record<string, string[]>>;
|
|
538
|
+
/**
|
|
539
|
+
* Tag definitions with descriptions
|
|
540
|
+
*/
|
|
541
|
+
tags?: TagObject[];
|
|
542
|
+
}
|
|
543
|
+
/**
|
|
544
|
+
* Service responsible for generating the complete OpenAPI document.
|
|
545
|
+
*
|
|
546
|
+
* Orchestrates endpoint discovery, path generation, and document assembly.
|
|
547
|
+
*/
|
|
548
|
+
declare class OpenApiGeneratorService {
|
|
549
|
+
private readonly logger;
|
|
550
|
+
private readonly scanner;
|
|
551
|
+
private readonly pathBuilder;
|
|
552
|
+
/**
|
|
553
|
+
* Generates an OpenAPI document from loaded modules.
|
|
554
|
+
*
|
|
555
|
+
* @param modules - Map of loaded modules
|
|
556
|
+
* @param options - OpenAPI generation options
|
|
557
|
+
* @returns Complete OpenAPI document
|
|
558
|
+
*/
|
|
559
|
+
generate(modules: Map<string, ModuleMetadata>, options: OpenApiGeneratorOptions): OpenAPIObject;
|
|
560
|
+
/**
|
|
561
|
+
* Builds paths object from discovered endpoints
|
|
562
|
+
*/
|
|
563
|
+
private buildPaths;
|
|
564
|
+
/**
|
|
565
|
+
* Collects unique tags from endpoints
|
|
566
|
+
*/
|
|
567
|
+
private collectTags;
|
|
568
|
+
/**
|
|
569
|
+
* Merges discovered tags with configured tags
|
|
570
|
+
*/
|
|
571
|
+
private mergeTags;
|
|
572
|
+
}
|
|
573
|
+
//#endregion
|
|
574
|
+
//#region src/tokens/index.d.mts
|
|
575
|
+
/**
|
|
576
|
+
* Tokens for OpenAPI metadata attributes
|
|
577
|
+
*/
|
|
578
|
+
/** Token for @ApiTag decorator */
|
|
579
|
+
declare const ApiTagToken: unique symbol;
|
|
580
|
+
/** Token for @ApiOperation decorator */
|
|
581
|
+
declare const ApiOperationToken: unique symbol;
|
|
582
|
+
/** Token for @ApiSummary decorator */
|
|
583
|
+
declare const ApiSummaryToken: unique symbol;
|
|
584
|
+
/** Token for @ApiDeprecated decorator */
|
|
585
|
+
declare const ApiDeprecatedToken: unique symbol;
|
|
586
|
+
/** Token for @ApiSecurity decorator */
|
|
587
|
+
declare const ApiSecurityToken: unique symbol;
|
|
588
|
+
/** Token for @ApiExclude decorator */
|
|
589
|
+
declare const ApiExcludeToken: unique symbol;
|
|
590
|
+
/** Token for @ApiStream decorator */
|
|
591
|
+
declare const ApiStreamToken: unique symbol;
|
|
592
|
+
//#endregion
|
|
593
|
+
export { ApiDeprecated, type ApiDeprecatedOptions, ApiDeprecatedToken, ApiExclude, ApiExcludeToken, ApiOperation, type ApiOperationOptions, ApiOperationToken, ApiSecurity, type ApiSecurityRequirement, ApiSecurityToken, ApiStream, type ApiStreamOptions, ApiStreamToken, ApiSummary, ApiSummaryToken, ApiTag, type ApiTagOptions, ApiTagToken, type DiscoveredEndpoint, EndpointScannerService, MetadataExtractorService, type OpenApiEndpointMetadata, type OpenApiGeneratorOptions, OpenApiGeneratorService, PathBuilderService, type PathItemResult, type SchemaConversionResult, SchemaConverterService };
|
|
594
|
+
//# sourceMappingURL=index.d.mts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.mts","names":[],"sources":["../src/decorators/api-tag.decorator.mts","../src/decorators/api-operation.decorator.mts","../src/decorators/api-summary.decorator.mts","../src/decorators/api-deprecated.decorator.mts","../src/decorators/api-security.decorator.mts","../src/decorators/api-exclude.decorator.mts","../src/decorators/api-stream.decorator.mts","../src/metadata/openapi.metadata.mts","../src/services/endpoint-scanner.service.mts","../src/services/metadata-extractor.service.mts","../src/services/schema-converter.service.mts","../src/services/path-builder.service.mts","../src/services/openapi-generator.service.mts","../src/tokens/index.mts"],"sourcesContent":[],"mappings":";;;;;;;cAKM,cAAY,CAAA,CAAA;;;;;KAMN,aAAA,GAAgB,CAAA,CAAE,aAAa;AAVjB;;;;;;;AAU1B;AAoCA;;;;;;;;;AC9C0B;;;;;;;;;;;;;;;iBD8CV,MAAA,kDAAyC,YAAA,wBAAA,gCAAA;;;cC1CnD,oBAAkB,CAAA,CAAA;;;;;;IDAlB,GAAA,aAGJ;;;;;AAHgB,KCcN,mBAAA,GAAsB,CAAA,CAAE,KDdlB,CAAA,OCc+B,kBDd/B,CAAA;;AAMlB;AAoCA;;;;;;;;;AC9C0B;;;;;;;;;;;;;;;;;;AAkB1B;AAmCA;;;cAAa,cAAY,aAAA,CAAA,qBAAA,CAAA,CAAA;;;;;;;;;;;;;;;;;;ADrDC;;;;;;;AAU1B;AAoCA;;;;;;;cEnBa,YAAU,aAAA,CAAA,qBAAA,CAAA,CAAA;;;cCvBjB,qBAAmB,CAAA,CAAA;;;;KAKb,oBAAA,GAAuB,CAAA,CAAE,aAAa;;AHTxB;;;;;;;AAU1B;AAoCA;;;;;;;;;AC9C0B;;;;;;iBEwCV,aAAA,gCAA8B,YAAA,wBAAA,gCAAA;;;cCpCxC,mBAAiB,CAAA,CAAA,UAAA,CAAA,CAAA,WAAA,CAAA,CAAA,SAAA,CAAA,CAAA;;KAGX,sBAAA,GAAyB,CAAA,CAAE,aAAa;;;;AJP1B;;;;;;;AAU1B;AAoCA;;;;;;;;;AC9C0B;;;;;;;;;cGsCb,aAAW,aAAA,CAAA,qBAAA,CAAA,CAAA,UAAA,CAAA,CAAA,WAAA,CAAA,CAAA,SAAA,CAAA,CAAA;;;;;;;;;;AJtCE;;;;;;;AAU1B;AAoCA;;;;;;;;;AC1CM,cIuBO,UJZX,EIYyE,aAAA,CAApD,cJZrB;;;cKXI,iBAAe,CAAA,CAAA;;;;;KAMT,gBAAA,GAAmB,CAAA,CAAE,aAAa;ANVpB;;;;;;;AAU1B;AAoCA;;;;;;;;;AC9C0B;;;;;;;;;;;;;;;;;;AAkB1B;AAmCA;cKJa,WAAS,aAAA,CAAA,qBAAA,CAAA,CAAA;;;;;;;;;UC7CL,uBAAA;;;EPAX;;;;;EAAY,WAAA,CAAA,EAAA,MAAA;EAAA;EAMN,UAAA,EAAA,OAAa;EAoCT;EAAyC,kBAAA,CAAA,EAAA,MAAA;EAAA;EAAA,QAAA,CAAA,EO5B5C,sBP4B4C,EAAA;EAAA;EAAA,YAAA,CAAA,EAAA;;;;EC1CnD;WMqBK;;;;;;;;;UCVM,kBAAA;ERXX;UQaI;;;;ERbQ,UAAA,EQiBJ,kBRjBI;EAAA;EAMN,OAAA,EQaD,eRbc,CAAA,GAAkB,CAAA;EAoC3B;EAAyC,MAAA,EQrB/C,kBRqB+C;EAAA;EAAA,eAAA,EQnBtC,uBRmBsC;;;;;;AC9C/B;;cOqCb,sBAAA;;;;;;;;;gBAaG,YAAY,kBAAkB;;;;;;;;;;;;;ARlDpB;cSsBb,wBAAA;;;;;;ATZb;AAoCA;EAAyD,OAAA,CAAA,UAAA,ESfzC,kBTeyC,EAAA,OAAA,ESd5C,eTc4C,CAAA,GAAA,CAAA,CAAA,ESbpD,uBTaoD;;;;KUzCpD,YAAA,GAAe,KAAA,CAAM;KACrB,eAAA,GAAkB,KAAA,CAAM;;;;AVFvB,UUOW,sBAAA,CVJf;UUKQ,eAAe;cACX,eAAe;;;;;AVH7B;AAoCA;;AAAyD,cUvB5C,sBAAA,CVuB4C;EAAA;;;;;;AC9C/B;;;;;;;;;;;kBSyCR,UAAU;;;;;;;ATvB5B;AAmCA;uBSAuB;;;;;;;;;sCAaP,eAAe,gBAC1B,eAAe;;;;KCjDf,cAAA,GAAiB,KAAA,CAAM;;;;AXdtB,UWsBW,cAAA,CXnBf;;YWqBU;;;;;AXlBZ;AAoCA;;AAAyD,cWR5C,kBAAA,CXQ4C;EAAA,iBAAA,eAAA;EAAA;;;;;AC9C/B;kBU+CR,qBAAqB;;;;;;;;;;;;2BAmD1B;;;;EV9FW,QAAA,eAAA;EAcZ;AAmCZ;;;;;;;;;;;;;;;;;;EAAyB,QAAA,kBAAA;;;;EC1BZ,QAAA,oBAAU;;;;ECvBjB,QAAA,gBAEJ;;;;KSGG,aAAA,GAAgB,KAAA,CAAM;KAEtB,oBAAA,GAAuB,KAAA,CAAM;KAC7B,SAAA,GAAY,KAAA,CAAM;;;AZZG;UYiBT,uBAAA;;;;EZbC,IAAA,EAAA;IAAA,KAAA,EAAA,MAAA;IAMN,OAAA,EAAA,MAAa;IAoCT,WAAM,CAAA,EAAA,MAAA;IAAmC,cAAA,CAAA,EAAA,MAAA;IAAA,OAAA,CAAA,EAAA;MAAA,IAAA,CAAA,EAAA,MAAA;MAAA,GAAA,CAAA,EAAA,MAAA;MAAA,KAAA,CAAA,EAAA,MAAA;;;;MC1CnD,GAAA,CAAA,EAAA,MAAA;;;;;;;;;;;;;YW4CM;;;IX5CY,SAAA,CAAA,EW+CR,MX/CQ,CAAA,MAAA,EAAA;MAAA,OAAA,EAAA,MAAA;MAcZ,IAAA,CAAA,EAAA,MAAA,EAAmB;MAmClB,WAGZ,CAAA,EAAA,MAAA;;;;;;oBWQmB,eAAe;;;;aAKtB,MAAM;;;;SAKV;;;;;;;cASI,uBAAA;EVxDA,iBAGZ,MAAA;;;;AC9ByB;;;;;;EASd,QAAA,CAAA,OAAA,ES0FC,GT1FD,CAAA,MAAoB,ES0FP,cT1FyB,CAAA,EAAA,OAAA,ES2FrC,uBT3F6B,CAAA,ES4FrC,aT5FqC;EA+B1B;;;EAA8B,QAAA,UAAA;EAAA;;;;;ACxCpB;;EAIH,QAAA,SAAA;;;;;;;;cSAV;;cAGA;AbPa;caUb;;cAGA;;AbTK,caYL,gBbZK,EAAA,OAAA,MAAA;;AAMN,caSC,ebT8B,EAAA,OAAA,MAAb;AAoC9B;AAAyD,caxB5C,cbwB4C,EAAA,OAAA,MAAA"}
|