@skmtc/core 0.0.791 → 0.0.793
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/esm/dsl/GeneratedValueList.d.ts +158 -0
- package/esm/dsl/GeneratedValueList.d.ts.map +1 -1
- package/esm/dsl/GeneratedValueList.js +158 -0
- package/esm/dsl/Stringable.d.ts +76 -0
- package/esm/dsl/Stringable.d.ts.map +1 -1
- package/esm/dsl/Stringable.js +75 -0
- package/esm/helpers/collateExamples.d.ts +150 -0
- package/esm/helpers/collateExamples.d.ts.map +1 -1
- package/esm/helpers/collateExamples.js +145 -0
- package/esm/helpers/formatNumber.d.ts +95 -0
- package/esm/helpers/formatNumber.d.ts.map +1 -1
- package/esm/helpers/formatNumber.js +95 -0
- package/esm/helpers/generationStats.d.ts +287 -1
- package/esm/helpers/generationStats.d.ts.map +1 -1
- package/esm/helpers/generationStats.js +266 -0
- package/esm/helpers/isEmpty.d.ts +62 -0
- package/esm/helpers/isEmpty.d.ts.map +1 -1
- package/esm/helpers/isEmpty.js +62 -0
- package/esm/helpers/isImported.d.ts +80 -0
- package/esm/helpers/isImported.d.ts.map +1 -1
- package/esm/helpers/isImported.js +80 -0
- package/esm/helpers/naming.d.ts +65 -1
- package/esm/helpers/naming.d.ts.map +1 -1
- package/esm/helpers/naming.js +65 -1
- package/esm/helpers/parseModuleName.d.ts +175 -0
- package/esm/helpers/parseModuleName.d.ts.map +1 -1
- package/esm/helpers/parseModuleName.js +153 -0
- package/esm/helpers/toResolvedArtifactPath.d.ts +145 -0
- package/esm/helpers/toResolvedArtifactPath.d.ts.map +1 -1
- package/esm/helpers/toResolvedArtifactPath.js +140 -0
- package/esm/oas/example/Example.d.ts +81 -1
- package/esm/oas/example/Example.d.ts.map +1 -1
- package/esm/oas/example/Example.js +74 -1
- package/esm/oas/header/Header.d.ts +217 -1
- package/esm/oas/header/Header.d.ts.map +1 -1
- package/esm/oas/header/Header.js +207 -1
- package/esm/oas/info/Info.d.ts +72 -0
- package/esm/oas/info/Info.d.ts.map +1 -1
- package/esm/oas/info/Info.js +62 -0
- package/esm/oas/mediaType/MediaType.d.ts +85 -0
- package/esm/oas/mediaType/MediaType.d.ts.map +1 -1
- package/esm/oas/mediaType/MediaType.js +77 -0
- package/esm/oas/pathItem/PathItem.d.ts +92 -0
- package/esm/oas/pathItem/PathItem.d.ts.map +1 -1
- package/esm/oas/pathItem/PathItem.js +85 -0
- package/esm/oas/requestBody/RequestBody.d.ts +264 -0
- package/esm/oas/requestBody/RequestBody.d.ts.map +1 -1
- package/esm/oas/requestBody/RequestBody.js +257 -0
- package/esm/oas/schema/Schema.d.ts +117 -0
- package/esm/oas/schema/Schema.d.ts.map +1 -1
- package/esm/typescript/identifiers.d.ts +159 -0
- package/esm/typescript/identifiers.d.ts.map +1 -1
- package/esm/typescript/identifiers.js +159 -0
- package/esm/typescript/withDescription.d.ts +119 -0
- package/esm/typescript/withDescription.d.ts.map +1 -1
- package/esm/typescript/withDescription.js +119 -0
- package/package.json +1 -1
- package/script/dsl/GeneratedValueList.d.ts +158 -0
- package/script/dsl/GeneratedValueList.d.ts.map +1 -1
- package/script/dsl/GeneratedValueList.js +158 -0
- package/script/dsl/Stringable.d.ts +76 -0
- package/script/dsl/Stringable.d.ts.map +1 -1
- package/script/dsl/Stringable.js +75 -0
- package/script/helpers/collateExamples.d.ts +150 -0
- package/script/helpers/collateExamples.d.ts.map +1 -1
- package/script/helpers/collateExamples.js +145 -0
- package/script/helpers/formatNumber.d.ts +95 -0
- package/script/helpers/formatNumber.d.ts.map +1 -1
- package/script/helpers/formatNumber.js +95 -0
- package/script/helpers/generationStats.d.ts +287 -1
- package/script/helpers/generationStats.d.ts.map +1 -1
- package/script/helpers/generationStats.js +266 -0
- package/script/helpers/isEmpty.d.ts +62 -0
- package/script/helpers/isEmpty.d.ts.map +1 -1
- package/script/helpers/isEmpty.js +62 -0
- package/script/helpers/isImported.d.ts +80 -0
- package/script/helpers/isImported.d.ts.map +1 -1
- package/script/helpers/isImported.js +80 -0
- package/script/helpers/naming.d.ts +65 -1
- package/script/helpers/naming.d.ts.map +1 -1
- package/script/helpers/naming.js +65 -1
- package/script/helpers/parseModuleName.d.ts +175 -0
- package/script/helpers/parseModuleName.d.ts.map +1 -1
- package/script/helpers/parseModuleName.js +153 -0
- package/script/helpers/toResolvedArtifactPath.d.ts +145 -0
- package/script/helpers/toResolvedArtifactPath.d.ts.map +1 -1
- package/script/helpers/toResolvedArtifactPath.js +140 -0
- package/script/oas/example/Example.d.ts +81 -1
- package/script/oas/example/Example.d.ts.map +1 -1
- package/script/oas/example/Example.js +74 -1
- package/script/oas/header/Header.d.ts +217 -1
- package/script/oas/header/Header.d.ts.map +1 -1
- package/script/oas/header/Header.js +207 -1
- package/script/oas/info/Info.d.ts +72 -0
- package/script/oas/info/Info.d.ts.map +1 -1
- package/script/oas/info/Info.js +62 -0
- package/script/oas/mediaType/MediaType.d.ts +85 -0
- package/script/oas/mediaType/MediaType.d.ts.map +1 -1
- package/script/oas/mediaType/MediaType.js +77 -0
- package/script/oas/pathItem/PathItem.d.ts +92 -0
- package/script/oas/pathItem/PathItem.d.ts.map +1 -1
- package/script/oas/pathItem/PathItem.js +85 -0
- package/script/oas/requestBody/RequestBody.d.ts +264 -0
- package/script/oas/requestBody/RequestBody.d.ts.map +1 -1
- package/script/oas/requestBody/RequestBody.js +257 -0
- package/script/oas/schema/Schema.d.ts +117 -0
- package/script/oas/schema/Schema.d.ts.map +1 -1
- package/script/typescript/identifiers.d.ts +159 -0
- package/script/typescript/identifiers.d.ts.map +1 -1
- package/script/typescript/identifiers.js +159 -0
- package/script/typescript/withDescription.d.ts +119 -0
- package/script/typescript/withDescription.d.ts.map +1 -1
- package/script/typescript/withDescription.js +119 -0
|
@@ -1,5 +1,145 @@
|
|
|
1
1
|
import "../_dnt.polyfills.js";
|
|
2
2
|
import { join } from '../deps/jsr.io/@std/path/1.1.2/join.js';
|
|
3
|
+
/**
|
|
4
|
+
* Resolves artifact destination paths relative to a base directory.
|
|
5
|
+
*
|
|
6
|
+
* This utility function combines a base path with a destination path to create
|
|
7
|
+
* the final resolved file path for generated artifacts. It handles special path
|
|
8
|
+
* prefixes (like '@/') and provides sensible defaults when no base path is specified.
|
|
9
|
+
*
|
|
10
|
+
* The function is used throughout the rendering pipeline to determine the final
|
|
11
|
+
* file system locations for generated code artifacts, ensuring consistent path
|
|
12
|
+
* resolution across different operating systems and deployment scenarios.
|
|
13
|
+
*
|
|
14
|
+
* @param args - Path resolution configuration
|
|
15
|
+
* @param args.basePath - Base directory path (defaults to './' if undefined)
|
|
16
|
+
* @param args.destinationPath - Destination path for the artifact
|
|
17
|
+
* @returns The resolved absolute or relative path for the artifact
|
|
18
|
+
*
|
|
19
|
+
* @example Basic path resolution
|
|
20
|
+
* ```typescript
|
|
21
|
+
* import { toResolvedArtifactPath } from '@skmtc/core';
|
|
22
|
+
*
|
|
23
|
+
* // With explicit base path
|
|
24
|
+
* const resolved1 = toResolvedArtifactPath({
|
|
25
|
+
* basePath: './src/generated',
|
|
26
|
+
* destinationPath: 'models/User.ts'
|
|
27
|
+
* });
|
|
28
|
+
* console.log(resolved1); // './src/generated/models/User.ts'
|
|
29
|
+
*
|
|
30
|
+
* // With undefined base path (uses default)
|
|
31
|
+
* const resolved2 = toResolvedArtifactPath({
|
|
32
|
+
* basePath: undefined,
|
|
33
|
+
* destinationPath: 'types.ts'
|
|
34
|
+
* });
|
|
35
|
+
* console.log(resolved2); // './types.ts'
|
|
36
|
+
* ```
|
|
37
|
+
*
|
|
38
|
+
* @example Special path prefix handling
|
|
39
|
+
* ```typescript
|
|
40
|
+
* // '@/' prefix gets stripped and resolved relative to base
|
|
41
|
+
* const resolved = toResolvedArtifactPath({
|
|
42
|
+
* basePath: './output',
|
|
43
|
+
* destinationPath: '@/api/models.ts'
|
|
44
|
+
* });
|
|
45
|
+
* console.log(resolved); // './output/api/models.ts'
|
|
46
|
+
*
|
|
47
|
+
* // Regular paths work normally
|
|
48
|
+
* const normal = toResolvedArtifactPath({
|
|
49
|
+
* basePath: './build',
|
|
50
|
+
* destinationPath: 'components/Button.tsx'
|
|
51
|
+
* });
|
|
52
|
+
* console.log(normal); // './build/components/Button.tsx'
|
|
53
|
+
* ```
|
|
54
|
+
*
|
|
55
|
+
* @example Cross-platform path resolution
|
|
56
|
+
* ```typescript
|
|
57
|
+
* // Works consistently across platforms
|
|
58
|
+
* const windowsPath = toResolvedArtifactPath({
|
|
59
|
+
* basePath: 'C:\\projects\\app\\dist',
|
|
60
|
+
* destinationPath: 'utils/helpers.js'
|
|
61
|
+
* });
|
|
62
|
+
*
|
|
63
|
+
* const unixPath = toResolvedArtifactPath({
|
|
64
|
+
* basePath: '/home/user/projects/app/dist',
|
|
65
|
+
* destinationPath: 'utils/helpers.js'
|
|
66
|
+
* });
|
|
67
|
+
* ```
|
|
68
|
+
*
|
|
69
|
+
* @example Usage in file generation
|
|
70
|
+
* ```typescript
|
|
71
|
+
* class ArtifactWriter {
|
|
72
|
+
* writeArtifact(
|
|
73
|
+
* content: string,
|
|
74
|
+
* destination: string,
|
|
75
|
+
* baseDir?: string
|
|
76
|
+
* ) {
|
|
77
|
+
* const resolvedPath = toResolvedArtifactPath({
|
|
78
|
+
* basePath: baseDir,
|
|
79
|
+
* destinationPath: destination
|
|
80
|
+
* });
|
|
81
|
+
*
|
|
82
|
+
* console.log(`Writing to: ${resolvedPath}`);
|
|
83
|
+
* return Deno.writeTextFile(resolvedPath, content);
|
|
84
|
+
* }
|
|
85
|
+
* }
|
|
86
|
+
*
|
|
87
|
+
* const writer = new ArtifactWriter();
|
|
88
|
+
* await writer.writeArtifact(
|
|
89
|
+
* 'export const greeting = "Hello";',
|
|
90
|
+
* '@/constants.ts',
|
|
91
|
+
* './src/generated'
|
|
92
|
+
* );
|
|
93
|
+
* // Writes to: ./src/generated/constants.ts
|
|
94
|
+
* ```
|
|
95
|
+
*
|
|
96
|
+
* @example Integration with rendering pipeline
|
|
97
|
+
* ```typescript
|
|
98
|
+
* class FileRenderer {
|
|
99
|
+
* renderFiles(
|
|
100
|
+
* files: Map<string, File>,
|
|
101
|
+
* outputDir: string
|
|
102
|
+
* ): Record<string, string> {
|
|
103
|
+
* const artifacts: Record<string, string> = {};
|
|
104
|
+
*
|
|
105
|
+
* for (const [destPath, file] of files) {
|
|
106
|
+
* const resolvedPath = toResolvedArtifactPath({
|
|
107
|
+
* basePath: outputDir,
|
|
108
|
+
* destinationPath: destPath
|
|
109
|
+
* });
|
|
110
|
+
*
|
|
111
|
+
* artifacts[resolvedPath] = file.toString();
|
|
112
|
+
* }
|
|
113
|
+
*
|
|
114
|
+
* return artifacts;
|
|
115
|
+
* }
|
|
116
|
+
* }
|
|
117
|
+
* ```
|
|
118
|
+
*
|
|
119
|
+
* @example Dynamic base path resolution
|
|
120
|
+
* ```typescript
|
|
121
|
+
* function resolveForEnvironment(
|
|
122
|
+
* destination: string,
|
|
123
|
+
* env: 'development' | 'production'
|
|
124
|
+
* ): string {
|
|
125
|
+
* const basePaths = {
|
|
126
|
+
* development: './dev-output',
|
|
127
|
+
* production: './dist'
|
|
128
|
+
* };
|
|
129
|
+
*
|
|
130
|
+
* return toResolvedArtifactPath({
|
|
131
|
+
* basePath: basePaths[env],
|
|
132
|
+
* destinationPath: destination
|
|
133
|
+
* });
|
|
134
|
+
* }
|
|
135
|
+
*
|
|
136
|
+
* const devPath = resolveForEnvironment('api.ts', 'development');
|
|
137
|
+
* const prodPath = resolveForEnvironment('api.ts', 'production');
|
|
138
|
+
*
|
|
139
|
+
* console.log(devPath); // './dev-output/api.ts'
|
|
140
|
+
* console.log(prodPath); // './dist/api.ts'
|
|
141
|
+
* ```
|
|
142
|
+
*/
|
|
3
143
|
export const toResolvedArtifactPath = ({ basePath, destinationPath }) => {
|
|
4
144
|
return join(basePath ?? './', destinationPath.replace(/^@\//, ''));
|
|
5
145
|
};
|
|
@@ -1,13 +1,93 @@
|
|
|
1
1
|
import type { OasRef } from '../ref/Ref.js';
|
|
2
2
|
import type { ToJsonSchemaOptions } from '../schema/Schema.js';
|
|
3
3
|
import type { OpenAPIV3 } from 'openapi-types';
|
|
4
|
+
/**
|
|
5
|
+
* Constructor fields for {@link OasExample}.
|
|
6
|
+
*/
|
|
4
7
|
export type ExampleFields = {
|
|
8
|
+
/** Short summary of the example */
|
|
5
9
|
summary: string | undefined;
|
|
10
|
+
/** Longer description of the example */
|
|
6
11
|
description: string | undefined;
|
|
12
|
+
/** The example value */
|
|
7
13
|
value: unknown;
|
|
14
|
+
/** Custom extension fields (x-* properties) */
|
|
8
15
|
extensionFields?: Record<string, unknown>;
|
|
9
16
|
};
|
|
10
|
-
/**
|
|
17
|
+
/**
|
|
18
|
+
* Represents an Example Object in the OpenAPI Specification.
|
|
19
|
+
*
|
|
20
|
+
* The `OasExample` class provides sample data for parameters, request bodies,
|
|
21
|
+
* responses, and other components in an OpenAPI document. Examples are crucial
|
|
22
|
+
* for API documentation, testing, and helping developers understand expected
|
|
23
|
+
* data formats and structures.
|
|
24
|
+
*
|
|
25
|
+
* This class supports rich example definitions with metadata, making API
|
|
26
|
+
* documentation more informative and interactive for developers.
|
|
27
|
+
*
|
|
28
|
+
* ## Key Features
|
|
29
|
+
*
|
|
30
|
+
* - **Sample Data**: Concrete examples of API inputs and outputs
|
|
31
|
+
* - **Documentation**: Summary and description for context
|
|
32
|
+
* - **Type Flexibility**: Supports any data type as example values
|
|
33
|
+
* - **Reference Support**: Can be referenced from multiple locations
|
|
34
|
+
* - **Markdown Support**: Rich text descriptions with CommonMark
|
|
35
|
+
*
|
|
36
|
+
* @example Simple string example
|
|
37
|
+
* ```typescript
|
|
38
|
+
* import { OasExample } from '@skmtc/core';
|
|
39
|
+
*
|
|
40
|
+
* const nameExample = new OasExample({
|
|
41
|
+
* summary: 'Typical user name',
|
|
42
|
+
* description: 'A common first and last name combination',
|
|
43
|
+
* value: 'John Doe'
|
|
44
|
+
* });
|
|
45
|
+
* ```
|
|
46
|
+
*
|
|
47
|
+
* @example JSON object example
|
|
48
|
+
* ```typescript
|
|
49
|
+
* const userExample = new OasExample({
|
|
50
|
+
* summary: 'Complete user profile',
|
|
51
|
+
* description: 'Example user with all profile fields populated',
|
|
52
|
+
* value: {
|
|
53
|
+
* id: 12345,
|
|
54
|
+
* name: 'Jane Smith',
|
|
55
|
+
* email: 'jane.smith@example.com',
|
|
56
|
+
* active: true,
|
|
57
|
+
* createdAt: '2023-01-15T10:30:00Z'
|
|
58
|
+
* }
|
|
59
|
+
* });
|
|
60
|
+
* ```
|
|
61
|
+
*
|
|
62
|
+
* @example Array example with multiple items
|
|
63
|
+
* ```typescript
|
|
64
|
+
* const productsExample = new OasExample({
|
|
65
|
+
* summary: 'Product list sample',
|
|
66
|
+
* description: 'Typical response for product catalog endpoint',
|
|
67
|
+
* value: [
|
|
68
|
+
* { id: 1, name: 'Laptop', price: 999.99, category: 'Electronics' },
|
|
69
|
+
* { id: 2, name: 'Book', price: 19.99, category: 'Education' },
|
|
70
|
+
* { id: 3, name: 'Coffee Mug', price: 12.50, category: 'Home' }
|
|
71
|
+
* ]
|
|
72
|
+
* });
|
|
73
|
+
* ```
|
|
74
|
+
*
|
|
75
|
+
* @example Error response example
|
|
76
|
+
* ```typescript
|
|
77
|
+
* const errorExample = new OasExample({
|
|
78
|
+
* summary: 'Validation error',
|
|
79
|
+
* description: 'Response when request validation fails',
|
|
80
|
+
* value: {
|
|
81
|
+
* error: 'Validation failed',
|
|
82
|
+
* code: 'INVALID_INPUT',
|
|
83
|
+
* details: [
|
|
84
|
+
* { field: 'email', message: 'Invalid email format' },
|
|
85
|
+
* { field: 'age', message: 'Must be between 18 and 120' }
|
|
86
|
+
* ]
|
|
87
|
+
* }
|
|
88
|
+
* });
|
|
89
|
+
* ```
|
|
90
|
+
*/
|
|
11
91
|
export declare class OasExample {
|
|
12
92
|
#private;
|
|
13
93
|
/** Static identifier property for OasExample */
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"Example.d.ts","sourceRoot":"","sources":["../../../src/oas/example/Example.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,KAAK,EAAE,OAAO,CAAA;IACd,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC1C,CAAA;AAED
|
|
1
|
+
{"version":3,"file":"Example.d.ts","sourceRoot":"","sources":["../../../src/oas/example/Example.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,mCAAmC;IACnC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B,wCAAwC;IACxC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,wBAAwB;IACxB,KAAK,EAAE,OAAO,CAAA;IACd,+CAA+C;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC1C,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH,qBAAa,UAAU;;IACrB,gDAAgD;IAChD,OAAO,EAAE,SAAS,CAAY;gBAIlB,MAAM,EAAE,aAAa;IAIjC,+BAA+B;IAC/B,IAAI,OAAO,IAAI,MAAM,GAAG,SAAS,CAEhC;IAED,2EAA2E;IAC3E,IAAI,WAAW,IAAI,MAAM,GAAG,SAAS,CAEpC;IAED,6BAA6B;IAC7B,IAAI,KAAK,IAAI,OAAO,CAEnB;IAED,qCAAqC;IACrC,IAAI,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAEzD;IAED,4CAA4C;IAC5C,KAAK,IAAI,IAAI,IAAI,MAAM,CAAC,SAAS,CAAC;IAIlC,qBAAqB;IACrB,OAAO,IAAI,UAAU;IAIrB,WAAW,IAAI,UAAU;IAIzB,YAAY,CAAC,QAAQ,EAAE,mBAAmB,GAAG,SAAS,CAAC,aAAa;CAOrE"}
|
|
@@ -10,7 +10,80 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
|
|
|
10
10
|
return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
|
|
11
11
|
};
|
|
12
12
|
var _OasExample_fields;
|
|
13
|
-
/**
|
|
13
|
+
/**
|
|
14
|
+
* Represents an Example Object in the OpenAPI Specification.
|
|
15
|
+
*
|
|
16
|
+
* The `OasExample` class provides sample data for parameters, request bodies,
|
|
17
|
+
* responses, and other components in an OpenAPI document. Examples are crucial
|
|
18
|
+
* for API documentation, testing, and helping developers understand expected
|
|
19
|
+
* data formats and structures.
|
|
20
|
+
*
|
|
21
|
+
* This class supports rich example definitions with metadata, making API
|
|
22
|
+
* documentation more informative and interactive for developers.
|
|
23
|
+
*
|
|
24
|
+
* ## Key Features
|
|
25
|
+
*
|
|
26
|
+
* - **Sample Data**: Concrete examples of API inputs and outputs
|
|
27
|
+
* - **Documentation**: Summary and description for context
|
|
28
|
+
* - **Type Flexibility**: Supports any data type as example values
|
|
29
|
+
* - **Reference Support**: Can be referenced from multiple locations
|
|
30
|
+
* - **Markdown Support**: Rich text descriptions with CommonMark
|
|
31
|
+
*
|
|
32
|
+
* @example Simple string example
|
|
33
|
+
* ```typescript
|
|
34
|
+
* import { OasExample } from '@skmtc/core';
|
|
35
|
+
*
|
|
36
|
+
* const nameExample = new OasExample({
|
|
37
|
+
* summary: 'Typical user name',
|
|
38
|
+
* description: 'A common first and last name combination',
|
|
39
|
+
* value: 'John Doe'
|
|
40
|
+
* });
|
|
41
|
+
* ```
|
|
42
|
+
*
|
|
43
|
+
* @example JSON object example
|
|
44
|
+
* ```typescript
|
|
45
|
+
* const userExample = new OasExample({
|
|
46
|
+
* summary: 'Complete user profile',
|
|
47
|
+
* description: 'Example user with all profile fields populated',
|
|
48
|
+
* value: {
|
|
49
|
+
* id: 12345,
|
|
50
|
+
* name: 'Jane Smith',
|
|
51
|
+
* email: 'jane.smith@example.com',
|
|
52
|
+
* active: true,
|
|
53
|
+
* createdAt: '2023-01-15T10:30:00Z'
|
|
54
|
+
* }
|
|
55
|
+
* });
|
|
56
|
+
* ```
|
|
57
|
+
*
|
|
58
|
+
* @example Array example with multiple items
|
|
59
|
+
* ```typescript
|
|
60
|
+
* const productsExample = new OasExample({
|
|
61
|
+
* summary: 'Product list sample',
|
|
62
|
+
* description: 'Typical response for product catalog endpoint',
|
|
63
|
+
* value: [
|
|
64
|
+
* { id: 1, name: 'Laptop', price: 999.99, category: 'Electronics' },
|
|
65
|
+
* { id: 2, name: 'Book', price: 19.99, category: 'Education' },
|
|
66
|
+
* { id: 3, name: 'Coffee Mug', price: 12.50, category: 'Home' }
|
|
67
|
+
* ]
|
|
68
|
+
* });
|
|
69
|
+
* ```
|
|
70
|
+
*
|
|
71
|
+
* @example Error response example
|
|
72
|
+
* ```typescript
|
|
73
|
+
* const errorExample = new OasExample({
|
|
74
|
+
* summary: 'Validation error',
|
|
75
|
+
* description: 'Response when request validation fails',
|
|
76
|
+
* value: {
|
|
77
|
+
* error: 'Validation failed',
|
|
78
|
+
* code: 'INVALID_INPUT',
|
|
79
|
+
* details: [
|
|
80
|
+
* { field: 'email', message: 'Invalid email format' },
|
|
81
|
+
* { field: 'age', message: 'Must be between 18 and 120' }
|
|
82
|
+
* ]
|
|
83
|
+
* }
|
|
84
|
+
* });
|
|
85
|
+
* ```
|
|
86
|
+
*/
|
|
14
87
|
export class OasExample {
|
|
15
88
|
constructor(fields) {
|
|
16
89
|
/** Static identifier property for OasExample */
|
|
@@ -4,16 +4,232 @@ import type { OasExample } from '../example/Example.js';
|
|
|
4
4
|
import type { OasSchema } from '../schema/Schema.js';
|
|
5
5
|
import type { ToJsonSchemaOptions } from '../schema/Schema.js';
|
|
6
6
|
import type { OpenAPIV3 } from 'openapi-types';
|
|
7
|
+
/**
|
|
8
|
+
* Constructor fields for {@link OasHeader}.
|
|
9
|
+
*/
|
|
7
10
|
export type HeaderFields = {
|
|
11
|
+
/** A brief description of the header */
|
|
8
12
|
description: string | undefined;
|
|
13
|
+
/** Whether the header is required */
|
|
9
14
|
required: boolean | undefined;
|
|
15
|
+
/** Whether the header is deprecated */
|
|
10
16
|
deprecated: boolean | undefined;
|
|
17
|
+
/** Schema defining the header's data type */
|
|
11
18
|
schema: OasSchema | OasRef<'schema'> | undefined;
|
|
19
|
+
/** Example values for the header */
|
|
12
20
|
examples: Record<string, OasExample | OasRef<'example'>> | undefined;
|
|
21
|
+
/** Content definitions for complex header values */
|
|
13
22
|
content: Record<string, OasMediaType> | undefined;
|
|
23
|
+
/** Custom extension fields (x-* properties) */
|
|
14
24
|
extensionFields?: Record<string, unknown>;
|
|
15
25
|
};
|
|
16
|
-
/**
|
|
26
|
+
/**
|
|
27
|
+
* Represents a Header Object in the OpenAPI Specification.
|
|
28
|
+
*
|
|
29
|
+
* The `OasHeader` class encapsulates the definition of a single HTTP header that
|
|
30
|
+
* can be sent with responses or expected in requests. Headers provide additional
|
|
31
|
+
* metadata about the HTTP message and can include authentication tokens, content
|
|
32
|
+
* information, pagination data, rate limiting details, and more.
|
|
33
|
+
*
|
|
34
|
+
* This class provides comprehensive support for header definitions with typed
|
|
35
|
+
* values, validation schemas, examples, and documentation.
|
|
36
|
+
*
|
|
37
|
+
* ## Key Features
|
|
38
|
+
*
|
|
39
|
+
* - **Schema Validation**: Typed header values through schema definitions
|
|
40
|
+
* - **Examples**: Multiple example values for documentation and testing
|
|
41
|
+
* - **Content Types**: Support for complex header values with media types
|
|
42
|
+
* - **Deprecation Support**: Mark headers as deprecated with proper warnings
|
|
43
|
+
* - **Required/Optional**: Control whether headers are mandatory
|
|
44
|
+
* - **Documentation**: Rich description support for API documentation
|
|
45
|
+
*
|
|
46
|
+
* @example Basic authentication header
|
|
47
|
+
* ```typescript
|
|
48
|
+
* import { OasHeader, OasString } from '@skmtc/core';
|
|
49
|
+
*
|
|
50
|
+
* const authHeader = new OasHeader({
|
|
51
|
+
* description: 'Bearer token for API authentication',
|
|
52
|
+
* required: true,
|
|
53
|
+
* schema: new OasString({
|
|
54
|
+
* pattern: '^Bearer [A-Za-z0-9+/=]+$',
|
|
55
|
+
* description: 'JWT bearer token'
|
|
56
|
+
* }),
|
|
57
|
+
* examples: {
|
|
58
|
+
* valid: new OasExample({
|
|
59
|
+
* summary: 'Valid bearer token',
|
|
60
|
+
* value: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
|
|
61
|
+
* })
|
|
62
|
+
* }
|
|
63
|
+
* });
|
|
64
|
+
* ```
|
|
65
|
+
*
|
|
66
|
+
* @example Pagination headers
|
|
67
|
+
* ```typescript
|
|
68
|
+
* const totalCountHeader = new OasHeader({
|
|
69
|
+
* description: 'Total number of items available',
|
|
70
|
+
* required: false,
|
|
71
|
+
* schema: new OasInteger({
|
|
72
|
+
* minimum: 0,
|
|
73
|
+
* description: 'Non-negative integer count'
|
|
74
|
+
* }),
|
|
75
|
+
* examples: {
|
|
76
|
+
* empty: new OasExample({ value: 0, description: 'No items' }),
|
|
77
|
+
* normal: new OasExample({ value: 150, description: 'Normal case' }),
|
|
78
|
+
* large: new OasExample({ value: 10000, description: 'Large dataset' })
|
|
79
|
+
* }
|
|
80
|
+
* });
|
|
81
|
+
*
|
|
82
|
+
* const linkHeader = new OasHeader({
|
|
83
|
+
* description: 'Pagination links (RFC 5988)',
|
|
84
|
+
* required: false,
|
|
85
|
+
* schema: new OasString({
|
|
86
|
+
* description: 'Comma-separated list of link relations'
|
|
87
|
+
* }),
|
|
88
|
+
* examples: {
|
|
89
|
+
* withNext: new OasExample({
|
|
90
|
+
* value: '</api/users?page=2>; rel="next", </api/users?page=10>; rel="last"'
|
|
91
|
+
* }),
|
|
92
|
+
* lastPage: new OasExample({
|
|
93
|
+
* value: '</api/users?page=9>; rel="prev", </api/users?page=1>; rel="first"'
|
|
94
|
+
* })
|
|
95
|
+
* }
|
|
96
|
+
* });
|
|
97
|
+
* ```
|
|
98
|
+
*
|
|
99
|
+
* @example Content type and encoding headers
|
|
100
|
+
* ```typescript
|
|
101
|
+
* const contentTypeHeader = new OasHeader({
|
|
102
|
+
* description: 'MIME type of the response content',
|
|
103
|
+
* required: true,
|
|
104
|
+
* schema: new OasString({
|
|
105
|
+
* enum: [
|
|
106
|
+
* 'application/json',
|
|
107
|
+
* 'application/xml',
|
|
108
|
+
* 'text/csv',
|
|
109
|
+
* 'application/pdf',
|
|
110
|
+
* 'application/octet-stream'
|
|
111
|
+
* ]
|
|
112
|
+
* }),
|
|
113
|
+
* examples: {
|
|
114
|
+
* json: new OasExample({ value: 'application/json' }),
|
|
115
|
+
* xml: new OasExample({ value: 'application/xml' }),
|
|
116
|
+
* csv: new OasExample({ value: 'text/csv' })
|
|
117
|
+
* }
|
|
118
|
+
* });
|
|
119
|
+
*
|
|
120
|
+
* const contentLengthHeader = new OasHeader({
|
|
121
|
+
* description: 'Size of the response body in bytes',
|
|
122
|
+
* required: false,
|
|
123
|
+
* schema: new OasInteger({
|
|
124
|
+
* minimum: 0,
|
|
125
|
+
* description: 'Content size in bytes'
|
|
126
|
+
* })
|
|
127
|
+
* });
|
|
128
|
+
* ```
|
|
129
|
+
*
|
|
130
|
+
* @example Rate limiting headers
|
|
131
|
+
* ```typescript
|
|
132
|
+
* const rateLimitHeader = new OasHeader({
|
|
133
|
+
* description: 'Number of requests remaining in the current window',
|
|
134
|
+
* required: false,
|
|
135
|
+
* schema: new OasInteger({
|
|
136
|
+
* minimum: 0,
|
|
137
|
+
* description: 'Remaining request count'
|
|
138
|
+
* }),
|
|
139
|
+
* examples: {
|
|
140
|
+
* available: new OasExample({ value: 95, description: '95 requests remaining' }),
|
|
141
|
+
* depleted: new OasExample({ value: 0, description: 'Rate limit reached' })
|
|
142
|
+
* }
|
|
143
|
+
* });
|
|
144
|
+
*
|
|
145
|
+
* const rateLimitResetHeader = new OasHeader({
|
|
146
|
+
* description: 'Unix timestamp when the rate limit window resets',
|
|
147
|
+
* required: false,
|
|
148
|
+
* schema: new OasInteger({
|
|
149
|
+
* minimum: 0,
|
|
150
|
+
* description: 'Unix timestamp in seconds'
|
|
151
|
+
* }),
|
|
152
|
+
* examples: {
|
|
153
|
+
* reset: new OasExample({
|
|
154
|
+
* value: 1634567890,
|
|
155
|
+
* description: 'Reset at 2021-10-18 12:31:30 UTC'
|
|
156
|
+
* })
|
|
157
|
+
* }
|
|
158
|
+
* });
|
|
159
|
+
* ```
|
|
160
|
+
*
|
|
161
|
+
* @example Custom application headers
|
|
162
|
+
* ```typescript
|
|
163
|
+
* const requestIdHeader = new OasHeader({
|
|
164
|
+
* description: 'Unique identifier for request tracing',
|
|
165
|
+
* required: false,
|
|
166
|
+
* schema: new OasString({
|
|
167
|
+
* format: 'uuid',
|
|
168
|
+
* description: 'UUID v4 request identifier'
|
|
169
|
+
* }),
|
|
170
|
+
* examples: {
|
|
171
|
+
* uuid: new OasExample({
|
|
172
|
+
* value: '123e4567-e89b-12d3-a456-426614174000',
|
|
173
|
+
* description: 'Request tracking ID'
|
|
174
|
+
* })
|
|
175
|
+
* }
|
|
176
|
+
* });
|
|
177
|
+
*
|
|
178
|
+
* const serverTimingHeader = new OasHeader({
|
|
179
|
+
* description: 'Server-side performance metrics',
|
|
180
|
+
* required: false,
|
|
181
|
+
* schema: new OasString({
|
|
182
|
+
* description: 'Server-Timing header format (RFC 8760)'
|
|
183
|
+
* }),
|
|
184
|
+
* examples: {
|
|
185
|
+
* timing: new OasExample({
|
|
186
|
+
* value: 'db;dur=53, app;dur=47.2',
|
|
187
|
+
* description: 'Database took 53ms, app logic 47.2ms'
|
|
188
|
+
* })
|
|
189
|
+
* }
|
|
190
|
+
* });
|
|
191
|
+
* ```
|
|
192
|
+
*
|
|
193
|
+
* @example Deprecated header
|
|
194
|
+
* ```typescript
|
|
195
|
+
* const deprecatedHeader = new OasHeader({
|
|
196
|
+
* description: 'Legacy API version header (deprecated)',
|
|
197
|
+
* required: false,
|
|
198
|
+
* deprecated: true,
|
|
199
|
+
* schema: new OasString({
|
|
200
|
+
* enum: ['v1', 'v2'],
|
|
201
|
+
* description: 'Use Accept or Content-Type header instead'
|
|
202
|
+
* }),
|
|
203
|
+
* examples: {
|
|
204
|
+
* legacy: new OasExample({
|
|
205
|
+
* value: 'v1',
|
|
206
|
+
* description: 'Legacy version (use Accept header instead)'
|
|
207
|
+
* })
|
|
208
|
+
* }
|
|
209
|
+
* });
|
|
210
|
+
* ```
|
|
211
|
+
*
|
|
212
|
+
* @example Using in response definitions
|
|
213
|
+
* ```typescript
|
|
214
|
+
* const successResponse = new OasResponse({
|
|
215
|
+
* description: 'Paginated user list',
|
|
216
|
+
* headers: {
|
|
217
|
+
* 'X-Total-Count': totalCountHeader,
|
|
218
|
+
* 'Link': linkHeader,
|
|
219
|
+
* 'X-Rate-Limit-Remaining': rateLimitHeader,
|
|
220
|
+
* 'X-Rate-Limit-Reset': rateLimitResetHeader,
|
|
221
|
+
* 'X-Request-ID': requestIdHeader
|
|
222
|
+
* },
|
|
223
|
+
* content: {
|
|
224
|
+
* 'application/json': new OasMediaType({
|
|
225
|
+
* schema: new OasArray({
|
|
226
|
+
* items: new OasRef({ $ref: '#/components/schemas/User' })
|
|
227
|
+
* })
|
|
228
|
+
* })
|
|
229
|
+
* }
|
|
230
|
+
* });
|
|
231
|
+
* ```
|
|
232
|
+
*/
|
|
17
233
|
export declare class OasHeader {
|
|
18
234
|
#private;
|
|
19
235
|
oasType: 'header';
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"Header.d.ts","sourceRoot":"","sources":["../../../src/oas/header/Header.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C,MAAM,MAAM,YAAY,GAAG;IACzB,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAA;IAC7B,UAAU,EAAE,OAAO,GAAG,SAAS,CAAA;IAC/B,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAA;IAChD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,SAAS,CAAA;IACpE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,SAAS,CAAA;IACjD,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC1C,CAAA;AAED
|
|
1
|
+
{"version":3,"file":"Header.d.ts","sourceRoot":"","sources":["../../../src/oas/header/Header.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,wCAAwC;IACxC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,qCAAqC;IACrC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAA;IAC7B,uCAAuC;IACvC,UAAU,EAAE,OAAO,GAAG,SAAS,CAAA;IAC/B,6CAA6C;IAC7C,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAA;IAChD,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,SAAS,CAAA;IACpE,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,SAAS,CAAA;IACjD,+CAA+C;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC1C,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8MG;AACH,qBAAa,SAAS;;IACpB,OAAO,EAAE,QAAQ,CAAW;gBAGhB,MAAM,EAAE,YAAY;IAIhC,kCAAkC;IAClC,IAAI,WAAW,IAAI,MAAM,GAAG,SAAS,CAEpC;IAED,iEAAiE;IACjE,IAAI,QAAQ,IAAI,OAAO,GAAG,SAAS,CAElC;IAED,6FAA6F;IAC7F,IAAI,UAAU,IAAI,OAAO,GAAG,SAAS,CAEpC;IAED,4BAA4B;IAC5B,IAAI,MAAM,IAAI,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,SAAS,CAErD;IAED,6BAA6B;IAC7B,IAAI,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,SAAS,CAEzE;IAED,4BAA4B;IAC5B,IAAI,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,SAAS,CAEtD;IAED,qCAAqC;IACrC,IAAI,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAEzD;IAED,4CAA4C;IAC5C,KAAK,IAAI,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC;IAIjC,qBAAqB;IACrB,OAAO,IAAI,SAAS;IAIpB,WAAW,IAAI,SAAS;IAIxB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,GAAE,MAA2B,GAAG,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC;IAc9E,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,SAAS,CAAC,YAAY;CASnE"}
|