@publier/openapi 0.3.38
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -0
- package/dist/generate.d.mts +156 -0
- package/dist/generate.mjs +1 -0
- package/dist/index.d.mts +461 -0
- package/dist/index.mjs +1 -0
- package/dist/parser.d.mts +136 -0
- package/dist/parser.mjs +1 -0
- package/dist/server.d.mts +238 -0
- package/dist/server.mjs +1 -0
- package/package.json +80 -0
- package/src/components/_collapsible-section.astro +14 -0
- package/src/components/_schema-row.astro +11 -0
- package/src/components/api-page.astro +21 -0
- package/src/components/api-playground-ce-element.ts +90 -0
- package/src/components/api-playground.astro +14 -0
- package/src/components/api-reference.astro +21 -0
- package/src/components/async-channel.astro +11 -0
- package/src/components/async-message.astro +10 -0
- package/src/components/code-samples.astro +28 -0
- package/src/components/method-badge.astro +26 -0
- package/src/components/param-field.astro +11 -0
- package/src/components/props.ts +91 -0
- package/src/components/request-example.astro +12 -0
- package/src/components/response-example.astro +17 -0
- package/src/components/response-field.astro +11 -0
- package/src/components/schema-view.astro +15 -0
package/README.md
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
# @publier/openapi
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
//#region src/types.d.ts
|
|
2
|
+
interface OpenApiSpec {
|
|
3
|
+
openapi: string;
|
|
4
|
+
info: OpenApiInfo;
|
|
5
|
+
servers?: OpenApiServer[];
|
|
6
|
+
paths: Record<string, OpenApiPathItem>;
|
|
7
|
+
/**
|
|
8
|
+
* OpenAPI 3.1 webhooks — server-to-client push endpoints, keyed by name.
|
|
9
|
+
* Shape-identical to path items but not part of the HTTP routing table.
|
|
10
|
+
*/
|
|
11
|
+
webhooks?: Record<string, OpenApiPathItem>;
|
|
12
|
+
components?: OpenApiComponents;
|
|
13
|
+
tags?: OpenApiTag[];
|
|
14
|
+
}
|
|
15
|
+
interface OpenApiInfo {
|
|
16
|
+
title: string;
|
|
17
|
+
description?: string;
|
|
18
|
+
version: string;
|
|
19
|
+
}
|
|
20
|
+
interface OpenApiServer {
|
|
21
|
+
url: string;
|
|
22
|
+
description?: string;
|
|
23
|
+
}
|
|
24
|
+
interface OpenApiPathItem {
|
|
25
|
+
get?: OpenApiOperation;
|
|
26
|
+
post?: OpenApiOperation;
|
|
27
|
+
put?: OpenApiOperation;
|
|
28
|
+
delete?: OpenApiOperation;
|
|
29
|
+
patch?: OpenApiOperation;
|
|
30
|
+
head?: OpenApiOperation;
|
|
31
|
+
options?: OpenApiOperation;
|
|
32
|
+
summary?: string;
|
|
33
|
+
description?: string;
|
|
34
|
+
parameters?: OpenApiParameter[];
|
|
35
|
+
}
|
|
36
|
+
interface OpenApiOperation {
|
|
37
|
+
operationId?: string;
|
|
38
|
+
summary?: string;
|
|
39
|
+
description?: string;
|
|
40
|
+
tags?: string[];
|
|
41
|
+
parameters?: OpenApiParameter[];
|
|
42
|
+
requestBody?: OpenApiRequestBody;
|
|
43
|
+
responses: Record<string, OpenApiResponse>;
|
|
44
|
+
/**
|
|
45
|
+
* OpenAPI 3.0+ callbacks — out-of-band requests the service will make in
|
|
46
|
+
* response to this operation.
|
|
47
|
+
*/
|
|
48
|
+
callbacks?: Record<string, Record<string, OpenApiPathItem>>;
|
|
49
|
+
security?: Record<string, string[]>[];
|
|
50
|
+
deprecated?: boolean;
|
|
51
|
+
'x-codeSamples'?: OpenApiCodeSample[];
|
|
52
|
+
}
|
|
53
|
+
interface OpenApiParameter {
|
|
54
|
+
name: string;
|
|
55
|
+
in: 'path' | 'query' | 'header' | 'cookie';
|
|
56
|
+
description?: string;
|
|
57
|
+
required?: boolean;
|
|
58
|
+
schema?: OpenApiSchema;
|
|
59
|
+
deprecated?: boolean;
|
|
60
|
+
}
|
|
61
|
+
interface OpenApiRequestBody {
|
|
62
|
+
description?: string;
|
|
63
|
+
required?: boolean;
|
|
64
|
+
content: Record<string, OpenApiMediaType>;
|
|
65
|
+
}
|
|
66
|
+
interface OpenApiResponse {
|
|
67
|
+
description: string;
|
|
68
|
+
content?: Record<string, OpenApiMediaType>;
|
|
69
|
+
headers?: Record<string, {
|
|
70
|
+
description?: string;
|
|
71
|
+
schema?: OpenApiSchema;
|
|
72
|
+
}>;
|
|
73
|
+
}
|
|
74
|
+
interface OpenApiMediaType {
|
|
75
|
+
schema?: OpenApiSchema;
|
|
76
|
+
example?: unknown;
|
|
77
|
+
examples?: Record<string, {
|
|
78
|
+
value: unknown;
|
|
79
|
+
summary?: string;
|
|
80
|
+
}>;
|
|
81
|
+
}
|
|
82
|
+
interface OpenApiSchema {
|
|
83
|
+
type?: string;
|
|
84
|
+
format?: string;
|
|
85
|
+
description?: string;
|
|
86
|
+
properties?: Record<string, OpenApiSchema>;
|
|
87
|
+
items?: OpenApiSchema;
|
|
88
|
+
required?: string[];
|
|
89
|
+
enum?: unknown[];
|
|
90
|
+
default?: unknown;
|
|
91
|
+
oneOf?: OpenApiSchema[];
|
|
92
|
+
anyOf?: OpenApiSchema[];
|
|
93
|
+
allOf?: OpenApiSchema[];
|
|
94
|
+
$ref?: string;
|
|
95
|
+
nullable?: boolean;
|
|
96
|
+
readOnly?: boolean;
|
|
97
|
+
writeOnly?: boolean;
|
|
98
|
+
deprecated?: boolean;
|
|
99
|
+
example?: unknown;
|
|
100
|
+
title?: string;
|
|
101
|
+
minimum?: number;
|
|
102
|
+
maximum?: number;
|
|
103
|
+
pattern?: string;
|
|
104
|
+
minLength?: number;
|
|
105
|
+
maxLength?: number;
|
|
106
|
+
additionalProperties?: boolean | OpenApiSchema;
|
|
107
|
+
}
|
|
108
|
+
interface OpenApiComponents {
|
|
109
|
+
schemas?: Record<string, OpenApiSchema>;
|
|
110
|
+
parameters?: Record<string, OpenApiParameter>;
|
|
111
|
+
responses?: Record<string, OpenApiResponse>;
|
|
112
|
+
requestBodies?: Record<string, OpenApiRequestBody>;
|
|
113
|
+
securitySchemes?: Record<string, OpenApiSecurityScheme>;
|
|
114
|
+
}
|
|
115
|
+
interface OpenApiSecurityScheme {
|
|
116
|
+
type: 'apiKey' | 'http' | 'oauth2' | 'openIdConnect';
|
|
117
|
+
description?: string;
|
|
118
|
+
name?: string;
|
|
119
|
+
in?: 'query' | 'header' | 'cookie';
|
|
120
|
+
scheme?: string;
|
|
121
|
+
bearerFormat?: string;
|
|
122
|
+
}
|
|
123
|
+
interface OpenApiTag {
|
|
124
|
+
name: string;
|
|
125
|
+
description?: string;
|
|
126
|
+
}
|
|
127
|
+
interface OpenApiCodeSample {
|
|
128
|
+
lang: string;
|
|
129
|
+
label?: string;
|
|
130
|
+
source: string;
|
|
131
|
+
}
|
|
132
|
+
//#endregion
|
|
133
|
+
//#region src/generate.d.ts
|
|
134
|
+
interface GenerateFilesOptions {
|
|
135
|
+
/** The parsed OpenAPI spec. */
|
|
136
|
+
spec: OpenApiSpec;
|
|
137
|
+
/** Output directory for generated MDX files. */
|
|
138
|
+
outputDir: string;
|
|
139
|
+
/** How to group endpoints. Default: 'tag'. */
|
|
140
|
+
groupBy?: 'tag' | 'path';
|
|
141
|
+
/** How many endpoints per file. Default: 'operation' (one file per endpoint). */
|
|
142
|
+
per?: 'operation' | 'tag';
|
|
143
|
+
/** Clean the output directory before generating. Default: true. */
|
|
144
|
+
clean?: boolean;
|
|
145
|
+
}
|
|
146
|
+
/**
|
|
147
|
+
* Generates individual MDX files from an OpenAPI spec.
|
|
148
|
+
*
|
|
149
|
+
* Each endpoint becomes a standalone MDX page with:
|
|
150
|
+
* - Frontmatter (title, description, method, path, tags)
|
|
151
|
+
* - Exported `operation` const with the full operation data
|
|
152
|
+
* - `<APIReference>` component rendering the endpoint
|
|
153
|
+
*/
|
|
154
|
+
declare function generateFiles(options: GenerateFilesOptions): string[];
|
|
155
|
+
//#endregion
|
|
156
|
+
export { GenerateFilesOptions, generateFiles };
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
import{openapiGenerateFiles as e}from"@publier/native";function t(t){let{spec:n,outputDir:r,groupBy:i=`tag`,per:a=`operation`,clean:o=!0}=t;return JSON.parse(e(JSON.stringify(n),r,i,a,o))}export{t as generateFiles};
|
package/dist/index.d.mts
ADDED
|
@@ -0,0 +1,461 @@
|
|
|
1
|
+
import { ContentSource } from "@publier/native";
|
|
2
|
+
|
|
3
|
+
//#region src/types.d.ts
|
|
4
|
+
interface OpenApiSpec {
|
|
5
|
+
openapi: string;
|
|
6
|
+
info: OpenApiInfo;
|
|
7
|
+
servers?: OpenApiServer[];
|
|
8
|
+
paths: Record<string, OpenApiPathItem>;
|
|
9
|
+
/**
|
|
10
|
+
* OpenAPI 3.1 webhooks — server-to-client push endpoints, keyed by name.
|
|
11
|
+
* Shape-identical to path items but not part of the HTTP routing table.
|
|
12
|
+
*/
|
|
13
|
+
webhooks?: Record<string, OpenApiPathItem>;
|
|
14
|
+
components?: OpenApiComponents;
|
|
15
|
+
tags?: OpenApiTag[];
|
|
16
|
+
}
|
|
17
|
+
interface OpenApiInfo {
|
|
18
|
+
title: string;
|
|
19
|
+
description?: string;
|
|
20
|
+
version: string;
|
|
21
|
+
}
|
|
22
|
+
interface OpenApiServer {
|
|
23
|
+
url: string;
|
|
24
|
+
description?: string;
|
|
25
|
+
}
|
|
26
|
+
interface OpenApiPathItem {
|
|
27
|
+
get?: OpenApiOperation;
|
|
28
|
+
post?: OpenApiOperation;
|
|
29
|
+
put?: OpenApiOperation;
|
|
30
|
+
delete?: OpenApiOperation;
|
|
31
|
+
patch?: OpenApiOperation;
|
|
32
|
+
head?: OpenApiOperation;
|
|
33
|
+
options?: OpenApiOperation;
|
|
34
|
+
summary?: string;
|
|
35
|
+
description?: string;
|
|
36
|
+
parameters?: OpenApiParameter[];
|
|
37
|
+
}
|
|
38
|
+
interface OpenApiOperation {
|
|
39
|
+
operationId?: string;
|
|
40
|
+
summary?: string;
|
|
41
|
+
description?: string;
|
|
42
|
+
tags?: string[];
|
|
43
|
+
parameters?: OpenApiParameter[];
|
|
44
|
+
requestBody?: OpenApiRequestBody;
|
|
45
|
+
responses: Record<string, OpenApiResponse>;
|
|
46
|
+
/**
|
|
47
|
+
* OpenAPI 3.0+ callbacks — out-of-band requests the service will make in
|
|
48
|
+
* response to this operation.
|
|
49
|
+
*/
|
|
50
|
+
callbacks?: Record<string, Record<string, OpenApiPathItem>>;
|
|
51
|
+
security?: Record<string, string[]>[];
|
|
52
|
+
deprecated?: boolean;
|
|
53
|
+
'x-codeSamples'?: OpenApiCodeSample[];
|
|
54
|
+
}
|
|
55
|
+
interface OpenApiParameter {
|
|
56
|
+
name: string;
|
|
57
|
+
in: 'path' | 'query' | 'header' | 'cookie';
|
|
58
|
+
description?: string;
|
|
59
|
+
required?: boolean;
|
|
60
|
+
schema?: OpenApiSchema;
|
|
61
|
+
deprecated?: boolean;
|
|
62
|
+
}
|
|
63
|
+
interface OpenApiRequestBody {
|
|
64
|
+
description?: string;
|
|
65
|
+
required?: boolean;
|
|
66
|
+
content: Record<string, OpenApiMediaType>;
|
|
67
|
+
}
|
|
68
|
+
interface OpenApiResponse {
|
|
69
|
+
description: string;
|
|
70
|
+
content?: Record<string, OpenApiMediaType>;
|
|
71
|
+
headers?: Record<string, {
|
|
72
|
+
description?: string;
|
|
73
|
+
schema?: OpenApiSchema;
|
|
74
|
+
}>;
|
|
75
|
+
}
|
|
76
|
+
interface OpenApiMediaType {
|
|
77
|
+
schema?: OpenApiSchema;
|
|
78
|
+
example?: unknown;
|
|
79
|
+
examples?: Record<string, {
|
|
80
|
+
value: unknown;
|
|
81
|
+
summary?: string;
|
|
82
|
+
}>;
|
|
83
|
+
}
|
|
84
|
+
interface OpenApiSchema {
|
|
85
|
+
type?: string;
|
|
86
|
+
format?: string;
|
|
87
|
+
description?: string;
|
|
88
|
+
properties?: Record<string, OpenApiSchema>;
|
|
89
|
+
items?: OpenApiSchema;
|
|
90
|
+
required?: string[];
|
|
91
|
+
enum?: unknown[];
|
|
92
|
+
default?: unknown;
|
|
93
|
+
oneOf?: OpenApiSchema[];
|
|
94
|
+
anyOf?: OpenApiSchema[];
|
|
95
|
+
allOf?: OpenApiSchema[];
|
|
96
|
+
$ref?: string;
|
|
97
|
+
nullable?: boolean;
|
|
98
|
+
readOnly?: boolean;
|
|
99
|
+
writeOnly?: boolean;
|
|
100
|
+
deprecated?: boolean;
|
|
101
|
+
example?: unknown;
|
|
102
|
+
title?: string;
|
|
103
|
+
minimum?: number;
|
|
104
|
+
maximum?: number;
|
|
105
|
+
pattern?: string;
|
|
106
|
+
minLength?: number;
|
|
107
|
+
maxLength?: number;
|
|
108
|
+
additionalProperties?: boolean | OpenApiSchema;
|
|
109
|
+
}
|
|
110
|
+
interface OpenApiComponents {
|
|
111
|
+
schemas?: Record<string, OpenApiSchema>;
|
|
112
|
+
parameters?: Record<string, OpenApiParameter>;
|
|
113
|
+
responses?: Record<string, OpenApiResponse>;
|
|
114
|
+
requestBodies?: Record<string, OpenApiRequestBody>;
|
|
115
|
+
securitySchemes?: Record<string, OpenApiSecurityScheme>;
|
|
116
|
+
}
|
|
117
|
+
interface OpenApiSecurityScheme {
|
|
118
|
+
type: 'apiKey' | 'http' | 'oauth2' | 'openIdConnect';
|
|
119
|
+
description?: string;
|
|
120
|
+
name?: string;
|
|
121
|
+
in?: 'query' | 'header' | 'cookie';
|
|
122
|
+
scheme?: string;
|
|
123
|
+
bearerFormat?: string;
|
|
124
|
+
}
|
|
125
|
+
interface OpenApiTag {
|
|
126
|
+
name: string;
|
|
127
|
+
description?: string;
|
|
128
|
+
}
|
|
129
|
+
interface OpenApiCodeSample {
|
|
130
|
+
lang: string;
|
|
131
|
+
label?: string;
|
|
132
|
+
source: string;
|
|
133
|
+
}
|
|
134
|
+
type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'head' | 'options';
|
|
135
|
+
//#endregion
|
|
136
|
+
//#region src/async-types.d.ts
|
|
137
|
+
interface AsyncApiSpec {
|
|
138
|
+
asyncapi: string;
|
|
139
|
+
info: {
|
|
140
|
+
title: string;
|
|
141
|
+
description?: string;
|
|
142
|
+
version: string;
|
|
143
|
+
};
|
|
144
|
+
servers?: Record<string, AsyncApiServer>;
|
|
145
|
+
channels?: Record<string, AsyncApiChannel>;
|
|
146
|
+
operations?: Record<string, AsyncApiOperation>;
|
|
147
|
+
components?: AsyncApiComponents;
|
|
148
|
+
}
|
|
149
|
+
interface AsyncApiServer {
|
|
150
|
+
host: string;
|
|
151
|
+
protocol: string;
|
|
152
|
+
pathname?: string;
|
|
153
|
+
description?: string;
|
|
154
|
+
tags?: {
|
|
155
|
+
name: string;
|
|
156
|
+
description?: string;
|
|
157
|
+
}[];
|
|
158
|
+
}
|
|
159
|
+
interface AsyncApiChannel {
|
|
160
|
+
address?: string;
|
|
161
|
+
description?: string;
|
|
162
|
+
messages?: Record<string, AsyncApiMessage | {
|
|
163
|
+
$ref: string;
|
|
164
|
+
}>;
|
|
165
|
+
parameters?: Record<string, AsyncApiParameter>;
|
|
166
|
+
tags?: {
|
|
167
|
+
name: string;
|
|
168
|
+
description?: string;
|
|
169
|
+
}[];
|
|
170
|
+
}
|
|
171
|
+
interface AsyncApiOperation {
|
|
172
|
+
action: 'send' | 'receive';
|
|
173
|
+
channel: {
|
|
174
|
+
$ref: string;
|
|
175
|
+
};
|
|
176
|
+
summary?: string;
|
|
177
|
+
description?: string;
|
|
178
|
+
messages?: ({
|
|
179
|
+
$ref: string;
|
|
180
|
+
} | AsyncApiMessage)[];
|
|
181
|
+
tags?: {
|
|
182
|
+
name: string;
|
|
183
|
+
description?: string;
|
|
184
|
+
}[];
|
|
185
|
+
}
|
|
186
|
+
interface AsyncApiMessage {
|
|
187
|
+
name?: string;
|
|
188
|
+
title?: string;
|
|
189
|
+
summary?: string;
|
|
190
|
+
description?: string;
|
|
191
|
+
contentType?: string;
|
|
192
|
+
payload?: OpenApiSchema;
|
|
193
|
+
headers?: OpenApiSchema;
|
|
194
|
+
tags?: {
|
|
195
|
+
name: string;
|
|
196
|
+
description?: string;
|
|
197
|
+
}[];
|
|
198
|
+
}
|
|
199
|
+
interface AsyncApiParameter {
|
|
200
|
+
description?: string;
|
|
201
|
+
default?: string;
|
|
202
|
+
enum?: string[];
|
|
203
|
+
}
|
|
204
|
+
interface AsyncApiComponents {
|
|
205
|
+
schemas?: Record<string, OpenApiSchema>;
|
|
206
|
+
messages?: Record<string, AsyncApiMessage>;
|
|
207
|
+
channels?: Record<string, AsyncApiChannel>;
|
|
208
|
+
operations?: Record<string, AsyncApiOperation>;
|
|
209
|
+
}
|
|
210
|
+
//#endregion
|
|
211
|
+
//#region src/async-source.d.ts
|
|
212
|
+
interface AsyncApiSourceOptions {
|
|
213
|
+
/** The parsed AsyncAPI spec. */
|
|
214
|
+
spec: AsyncApiSpec;
|
|
215
|
+
/** Base URL prefix for generated pages (e.g., '/async-reference'). */
|
|
216
|
+
baseUrl?: string;
|
|
217
|
+
}
|
|
218
|
+
/**
|
|
219
|
+
* Creates a ContentSource from a parsed AsyncAPI spec.
|
|
220
|
+
* Each channel becomes a virtual page grouped by tags.
|
|
221
|
+
*/
|
|
222
|
+
declare function asyncapiSource(options: AsyncApiSourceOptions): ContentSource;
|
|
223
|
+
//#endregion
|
|
224
|
+
//#region src/code-sample-generators.d.ts
|
|
225
|
+
type SampleLang = 'curl' | 'javascript' | 'python' | 'go' | 'java' | 'csharp';
|
|
226
|
+
declare function generateCodeSample(method: HttpMethod, path: string, operation: OpenApiOperation, lang: SampleLang, baseUrl: string): string;
|
|
227
|
+
//#endregion
|
|
228
|
+
//#region src/components/props.d.ts
|
|
229
|
+
interface APIReferenceProps {
|
|
230
|
+
method: HttpMethod;
|
|
231
|
+
path: string;
|
|
232
|
+
operation: OpenApiOperation;
|
|
233
|
+
spec?: OpenApiSpec;
|
|
234
|
+
baseUrl?: string;
|
|
235
|
+
}
|
|
236
|
+
interface APIPageProps {
|
|
237
|
+
method: HttpMethod;
|
|
238
|
+
path: string;
|
|
239
|
+
operation: OpenApiOperation;
|
|
240
|
+
}
|
|
241
|
+
interface MethodBadgeProps {
|
|
242
|
+
method: HttpMethod;
|
|
243
|
+
}
|
|
244
|
+
interface APIPlaygroundProps {
|
|
245
|
+
method: HttpMethod;
|
|
246
|
+
path: string;
|
|
247
|
+
operation: OpenApiOperation;
|
|
248
|
+
servers?: OpenApiServer[];
|
|
249
|
+
}
|
|
250
|
+
interface CodeSamplesProps {
|
|
251
|
+
method: HttpMethod;
|
|
252
|
+
path: string;
|
|
253
|
+
operation: OpenApiOperation;
|
|
254
|
+
baseUrl?: string;
|
|
255
|
+
}
|
|
256
|
+
interface RequestExampleProps {
|
|
257
|
+
method: HttpMethod;
|
|
258
|
+
path: string;
|
|
259
|
+
operation: OpenApiOperation;
|
|
260
|
+
baseUrl?: string;
|
|
261
|
+
}
|
|
262
|
+
interface ResponseExampleProps {
|
|
263
|
+
responses: Record<string, OpenApiResponse>;
|
|
264
|
+
instanceId?: string;
|
|
265
|
+
}
|
|
266
|
+
interface SchemaViewProps {
|
|
267
|
+
schema: OpenApiSchema;
|
|
268
|
+
name?: string;
|
|
269
|
+
required?: boolean;
|
|
270
|
+
depth?: number;
|
|
271
|
+
}
|
|
272
|
+
interface ParamFieldProps {
|
|
273
|
+
name: string;
|
|
274
|
+
type: string;
|
|
275
|
+
required?: boolean;
|
|
276
|
+
default?: string;
|
|
277
|
+
deprecated?: boolean;
|
|
278
|
+
placeholder?: string;
|
|
279
|
+
}
|
|
280
|
+
interface ResponseFieldProps {
|
|
281
|
+
name: string;
|
|
282
|
+
type: string;
|
|
283
|
+
required?: boolean;
|
|
284
|
+
deprecated?: boolean;
|
|
285
|
+
}
|
|
286
|
+
interface AsyncChannelProps {
|
|
287
|
+
channelName: string;
|
|
288
|
+
channel: AsyncApiChannel;
|
|
289
|
+
operations: {
|
|
290
|
+
name: string;
|
|
291
|
+
operation: AsyncApiOperation;
|
|
292
|
+
messages: AsyncApiMessage[];
|
|
293
|
+
}[];
|
|
294
|
+
servers?: Record<string, AsyncApiServer>;
|
|
295
|
+
}
|
|
296
|
+
interface AsyncMessageProps {
|
|
297
|
+
message: AsyncApiMessage;
|
|
298
|
+
}
|
|
299
|
+
//#endregion
|
|
300
|
+
//#region src/endpoints.d.ts
|
|
301
|
+
/** HTTP methods that may appear on an OpenAPI path item, in canonical order. */
|
|
302
|
+
declare const HTTP_METHODS: HttpMethod[];
|
|
303
|
+
/** The kind of endpoint — a regular HTTP path, or an OpenAPI 3.1 webhook. */
|
|
304
|
+
type EndpointKind = 'path' | 'webhook';
|
|
305
|
+
/** A single endpoint extracted from an OpenAPI spec. */
|
|
306
|
+
interface EndpointEntry {
|
|
307
|
+
method: HttpMethod;
|
|
308
|
+
path: string;
|
|
309
|
+
operation: OpenApiOperation;
|
|
310
|
+
/** `'path'` for `spec.paths`, `'webhook'` for `spec.webhooks`. Default `'path'`. */
|
|
311
|
+
kind?: EndpointKind;
|
|
312
|
+
}
|
|
313
|
+
interface ExtractEndpointsOptions {
|
|
314
|
+
/**
|
|
315
|
+
* When true, copy path-level `parameters` onto each operation that
|
|
316
|
+
* doesn't already define its own `parameters`. This matches the
|
|
317
|
+
* standard OpenAPI inheritance rule and is required when downstream
|
|
318
|
+
* code reads `operation.parameters` without consulting the path item.
|
|
319
|
+
*
|
|
320
|
+
* Defaults to `false` to preserve historical behavior of callers
|
|
321
|
+
* that walk the path item directly.
|
|
322
|
+
*/
|
|
323
|
+
mergePathParameters?: boolean;
|
|
324
|
+
/**
|
|
325
|
+
* When true (default), extract entries from `spec.webhooks` alongside
|
|
326
|
+
* `spec.paths`. Webhook entries have `kind: 'webhook'` so renderers can
|
|
327
|
+
* style them differently (and exclude from path-only nav lists).
|
|
328
|
+
*/
|
|
329
|
+
includeWebhooks?: boolean;
|
|
330
|
+
}
|
|
331
|
+
declare function extractEndpoints(spec: OpenApiSpec, options?: ExtractEndpointsOptions): EndpointEntry[];
|
|
332
|
+
//#endregion
|
|
333
|
+
//#region src/example-utils.d.ts
|
|
334
|
+
declare function generateExampleFromSchema(schema: OpenApiSchema): unknown;
|
|
335
|
+
declare function getMediaTypeExample(content: Record<string, OpenApiMediaType>, mediaType?: string): string | undefined;
|
|
336
|
+
declare function formatJson(value: unknown): string;
|
|
337
|
+
//#endregion
|
|
338
|
+
//#region src/generate.d.ts
|
|
339
|
+
interface GenerateFilesOptions {
|
|
340
|
+
/** The parsed OpenAPI spec. */
|
|
341
|
+
spec: OpenApiSpec;
|
|
342
|
+
/** Output directory for generated MDX files. */
|
|
343
|
+
outputDir: string;
|
|
344
|
+
/** How to group endpoints. Default: 'tag'. */
|
|
345
|
+
groupBy?: 'tag' | 'path';
|
|
346
|
+
/** How many endpoints per file. Default: 'operation' (one file per endpoint). */
|
|
347
|
+
per?: 'operation' | 'tag';
|
|
348
|
+
/** Clean the output directory before generating. Default: true. */
|
|
349
|
+
clean?: boolean;
|
|
350
|
+
}
|
|
351
|
+
//#endregion
|
|
352
|
+
//#region src/navigation.d.ts
|
|
353
|
+
/** A single navigation entry — typically one endpoint. */
|
|
354
|
+
interface NavigationItem {
|
|
355
|
+
/** Human-readable label (operation summary or fall-back). */
|
|
356
|
+
label: string;
|
|
357
|
+
/** URL-safe slug usable as a sidebar link or a page id. */
|
|
358
|
+
slug: string;
|
|
359
|
+
/** HTTP method, uppercase. */
|
|
360
|
+
method: string;
|
|
361
|
+
/** Path template (e.g. `/users/{id}`). */
|
|
362
|
+
path: string;
|
|
363
|
+
/** Present when the upstream operation is flagged deprecated. */
|
|
364
|
+
deprecated?: boolean;
|
|
365
|
+
/** `'webhook'` when this came from `spec.webhooks`, else `'path'`. */
|
|
366
|
+
kind?: 'path' | 'webhook';
|
|
367
|
+
}
|
|
368
|
+
/**
|
|
369
|
+
* A group of related endpoints — one per tag (default) or per first path
|
|
370
|
+
* segment. Maps naturally to a sidebar group entry.
|
|
371
|
+
*/
|
|
372
|
+
interface NavigationGroup {
|
|
373
|
+
label: string;
|
|
374
|
+
description?: string;
|
|
375
|
+
items: NavigationItem[];
|
|
376
|
+
}
|
|
377
|
+
interface BuildNavigationOptions {
|
|
378
|
+
/**
|
|
379
|
+
* How to group endpoints. `'tag'` is the OpenAPI norm; `'path'` groups by
|
|
380
|
+
* first non-parameter path segment (useful for specs without tags).
|
|
381
|
+
*/
|
|
382
|
+
groupBy?: 'tag' | 'path';
|
|
383
|
+
/**
|
|
384
|
+
* URL path prefixed onto every item slug. When the generated docs live
|
|
385
|
+
* under `/api`, pass `'api'` to get `api/<tag>/<operation>` slugs.
|
|
386
|
+
*/
|
|
387
|
+
slugPrefix?: string;
|
|
388
|
+
/**
|
|
389
|
+
* Override the default label (operation.summary or `METHOD path`).
|
|
390
|
+
* Note: this callback cannot cross the Rust boundary and is not applied.
|
|
391
|
+
* Apply a post-pass on the returned groups if custom labels are needed.
|
|
392
|
+
*/
|
|
393
|
+
formatLabel?: (ep: EndpointEntry) => string;
|
|
394
|
+
/**
|
|
395
|
+
* Drop deprecated operations from the output entirely. Default: keep them
|
|
396
|
+
* and expose the `deprecated` flag for renderers to style as needed.
|
|
397
|
+
*/
|
|
398
|
+
excludeDeprecated?: boolean;
|
|
399
|
+
/** Forwarded to `extractEndpoints` — see that function's docs. */
|
|
400
|
+
includeWebhooks?: boolean;
|
|
401
|
+
}
|
|
402
|
+
/**
|
|
403
|
+
* Build a navigation tree suitable for feeding into a sidebar or custom page
|
|
404
|
+
* tree. Stateless and side-effect-free.
|
|
405
|
+
*/
|
|
406
|
+
declare function buildNavigation(spec: OpenApiSpec, options?: BuildNavigationOptions): NavigationGroup[];
|
|
407
|
+
//#endregion
|
|
408
|
+
//#region src/server.d.ts
|
|
409
|
+
interface CreateOpenAPIOptions {
|
|
410
|
+
/**
|
|
411
|
+
* OpenAPI spec input — file paths (JSON/YAML), URLs, or raw spec objects.
|
|
412
|
+
* Multiple specs are merged by combining their paths.
|
|
413
|
+
*/
|
|
414
|
+
input: string[] | OpenApiSpec[];
|
|
415
|
+
/** Disable spec caching (re-parse on every access). */
|
|
416
|
+
disableCache?: boolean;
|
|
417
|
+
}
|
|
418
|
+
/** Resolved operation lookup result. */
|
|
419
|
+
interface ResolvedOperation {
|
|
420
|
+
method: HttpMethod;
|
|
421
|
+
path: string;
|
|
422
|
+
operation: OpenApiOperation;
|
|
423
|
+
}
|
|
424
|
+
interface OpenAPIServer {
|
|
425
|
+
/** Get the parsed and merged OpenAPI spec. */
|
|
426
|
+
getSpec(): Promise<OpenApiSpec>;
|
|
427
|
+
/**
|
|
428
|
+
* Look up an operation by its `operationId`. Returns `undefined` when no
|
|
429
|
+
* operation matches.
|
|
430
|
+
*/
|
|
431
|
+
getOperation(operationId: string): Promise<ResolvedOperation | undefined>;
|
|
432
|
+
/**
|
|
433
|
+
* Look up an operation by path + method (e.g. `'/users'`, `'get'`).
|
|
434
|
+
* Returns `undefined` when no operation matches.
|
|
435
|
+
*/
|
|
436
|
+
getOperationByPath(path: string, method: HttpMethod): Promise<ResolvedOperation | undefined>;
|
|
437
|
+
/**
|
|
438
|
+
* Return every operation tagged with the given tag (case-sensitive, matches
|
|
439
|
+
* OpenAPI's `tags: [...]` array).
|
|
440
|
+
*/
|
|
441
|
+
getOperationsByTag(tag: string): Promise<ResolvedOperation[]>;
|
|
442
|
+
/** Flat list of every extracted endpoint — paths and (by default) webhooks. */
|
|
443
|
+
getEndpoints(): Promise<EndpointEntry[]>;
|
|
444
|
+
/** Build a navigation tree from the merged spec. */
|
|
445
|
+
getNavigation(options?: BuildNavigationOptions): Promise<NavigationGroup[]>;
|
|
446
|
+
}
|
|
447
|
+
//#endregion
|
|
448
|
+
//#region src/source.d.ts
|
|
449
|
+
interface OpenApiSourceOptions {
|
|
450
|
+
/** The parsed OpenAPI spec. */
|
|
451
|
+
spec: OpenApiSpec;
|
|
452
|
+
/** Base URL prefix for generated pages (e.g., '/api-reference'). */
|
|
453
|
+
baseUrl?: string;
|
|
454
|
+
}
|
|
455
|
+
/**
|
|
456
|
+
* Creates a ContentSource from a parsed OpenAPI spec.
|
|
457
|
+
* Each endpoint (method + path) becomes a virtual page grouped by tags.
|
|
458
|
+
*/
|
|
459
|
+
declare function openapiSource(options: OpenApiSourceOptions): ContentSource;
|
|
460
|
+
//#endregion
|
|
461
|
+
export { type APIPageProps, type APIPlaygroundProps, type APIReferenceProps, type AsyncApiChannel, type AsyncApiComponents, type AsyncApiMessage, type AsyncApiOperation, type AsyncApiParameter, type AsyncApiServer, type AsyncApiSpec, type AsyncChannelProps, type AsyncMessageProps, type BuildNavigationOptions, type CodeSamplesProps, type CreateOpenAPIOptions, type EndpointEntry, type EndpointKind, type ExtractEndpointsOptions, type GenerateFilesOptions, HTTP_METHODS, type HttpMethod, type MethodBadgeProps, type NavigationGroup, type NavigationItem, type OpenAPIServer, type OpenApiCodeSample, type OpenApiComponents, type OpenApiInfo, type OpenApiMediaType, type OpenApiOperation, type OpenApiParameter, type OpenApiPathItem, type OpenApiRequestBody, type OpenApiResponse, type OpenApiSchema, type OpenApiSecurityScheme, type OpenApiServer, type OpenApiSpec, type OpenApiTag, type ParamFieldProps, type RequestExampleProps, type ResolvedOperation, type ResponseExampleProps, type ResponseFieldProps, type SchemaViewProps, asyncapiSource, buildNavigation, extractEndpoints, formatJson, generateCodeSample, generateExampleFromSchema, getMediaTypeExample, openapiSource };
|
package/dist/index.mjs
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
import{asyncapiSourceBuild as e,openapiDecodePlaceholders as t,openapiExtractEndpoints as n,openapiGetMediaTypeExample as r,openapiGetSnippetClient as i,openapiHarFromOperation as a,openapiNavigationBuild as o,openapiSourceBuild as s}from"@publier/native";import{HTTPSnippet as c}from"@readme/httpsnippet";import l from"openapi-sampler";function u(t){let{spec:n,baseUrl:r=``}=t,{pages:i,tree:a}=JSON.parse(e(JSON.stringify(n),r)),o=new Map(i.map(e=>[e.slug.join(`/`),e]));return{async getPage(e){return o.get(e.join(`/`))},async getPages(){return i},async getPageTree(){return a},async generateParams(){return i.map(e=>({slug:e.slug}))}}}function d(e,n,r,o,s){let l=i(o);if(!l)return``;let[u,d]=l,f=new c(JSON.parse(a(e,n,JSON.stringify(r),s))).convert(u,d),p=``;if(Array.isArray(f)){let e=f.find(e=>typeof e==`string`);typeof e==`string`&&(p=e)}else typeof f==`string`&&(p=f);return t(p)}const f=[`get`,`post`,`put`,`delete`,`patch`,`head`,`options`];function p(e,t={}){let{mergePathParameters:r=!1,includeWebhooks:i=!0}=t;return JSON.parse(n(JSON.stringify(e),r,i))}function m(e){return l.sample(e)}function h(e,t=`application/json`){let n=r(JSON.stringify(e),t);if(n===`__schema__`){let n=Object.keys(e)[0],r=e[t]??(n?e[n]:void 0);return r?.schema?g(m(r.schema)):void 0}return n??void 0}function g(e){return JSON.stringify(e,null,2)}function _(e,t={}){let{groupBy:n=`tag`,slugPrefix:r,excludeDeprecated:i=!1,includeWebhooks:a=!0}=t;return JSON.parse(o(JSON.stringify(e),n,r??null,i,a))}function v(e){let{spec:t,baseUrl:n=``}=e,{pages:r,tree:i}=JSON.parse(s(JSON.stringify(t),n)),a=new Map(r.map(e=>[e.slug.join(`/`),e]));return{async getPage(e){return a.get(e.join(`/`))},async getPages(){return r},async getPageTree(){return i},async generateParams(){return r.map(e=>({slug:e.slug}))}}}export{f as HTTP_METHODS,u as asyncapiSource,_ as buildNavigation,p as extractEndpoints,g as formatJson,d as generateCodeSample,m as generateExampleFromSchema,h as getMediaTypeExample,v as openapiSource};
|