@donghanh/hono 0.3.3 → 0.3.4
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/package.json +1 -1
- package/src/openapi.test.ts +89 -2
- package/src/openapi.ts +236 -33
package/package.json
CHANGED
package/src/openapi.test.ts
CHANGED
|
@@ -32,7 +32,7 @@ const servers = [{ url: "https://api.example.com" }];
|
|
|
32
32
|
const basePath = "/api/gpt";
|
|
33
33
|
|
|
34
34
|
describe("generateOpenApi common", () => {
|
|
35
|
-
test("emits 3.1.0 spec with info + servers +
|
|
35
|
+
test("emits 3.1.0 spec with info + servers + default bearer scheme", () => {
|
|
36
36
|
const spec = generateOpenApi({
|
|
37
37
|
registry: registry({ a: makeOp("a") }),
|
|
38
38
|
info,
|
|
@@ -46,7 +46,9 @@ describe("generateOpenApi common", () => {
|
|
|
46
46
|
type: "http",
|
|
47
47
|
scheme: "bearer",
|
|
48
48
|
});
|
|
49
|
-
|
|
49
|
+
// components.schemas always includes OperationResponse (validator requires object)
|
|
50
|
+
expect(typeof spec.components.schemas).toBe("object");
|
|
51
|
+
expect(spec.components.schemas.OperationResponse).toBeDefined();
|
|
50
52
|
});
|
|
51
53
|
|
|
52
54
|
test("includeDescription is off by default — no description field", () => {
|
|
@@ -106,6 +108,86 @@ describe("generateOpenApi common", () => {
|
|
|
106
108
|
expect(s.length).toBeLessThanOrEqual(120);
|
|
107
109
|
});
|
|
108
110
|
|
|
111
|
+
test("emits discovery endpoints by default (listOperations + getOperationDetail)", () => {
|
|
112
|
+
const spec = generateOpenApi({
|
|
113
|
+
registry: registry({ a: makeOp("a") }),
|
|
114
|
+
info,
|
|
115
|
+
servers,
|
|
116
|
+
basePath,
|
|
117
|
+
}) as any;
|
|
118
|
+
expect(spec.paths["/api/gpt/operations"].get.operationId).toBe(
|
|
119
|
+
"listOperations",
|
|
120
|
+
);
|
|
121
|
+
expect(spec.paths["/api/gpt/operations/{name}"].get.operationId).toBe(
|
|
122
|
+
"getOperationDetail",
|
|
123
|
+
);
|
|
124
|
+
expect(spec.paths["/api/gpt/operations"].get.security).toEqual([]);
|
|
125
|
+
expect(spec.paths["/api/gpt/operations/{name}"].get.security).toEqual([]);
|
|
126
|
+
});
|
|
127
|
+
|
|
128
|
+
test("includeDiscoveryEndpoints: false omits them", () => {
|
|
129
|
+
const spec = generateOpenApi({
|
|
130
|
+
registry: registry({ a: makeOp("a") }),
|
|
131
|
+
info,
|
|
132
|
+
servers,
|
|
133
|
+
basePath,
|
|
134
|
+
includeDiscoveryEndpoints: false,
|
|
135
|
+
}) as any;
|
|
136
|
+
expect(spec.paths["/api/gpt/operations"]).toBeUndefined();
|
|
137
|
+
expect(spec.paths["/api/gpt/operations/{name}"]).toBeUndefined();
|
|
138
|
+
});
|
|
139
|
+
|
|
140
|
+
test("emits OperationResponse component schema referenced by paths", () => {
|
|
141
|
+
const spec = generateOpenApi({
|
|
142
|
+
registry: registry({ a: makeOp("a") }),
|
|
143
|
+
info,
|
|
144
|
+
servers,
|
|
145
|
+
basePath,
|
|
146
|
+
pathStyle: "per-op",
|
|
147
|
+
}) as any;
|
|
148
|
+
expect(spec.components.schemas.OperationResponse.type).toBe("object");
|
|
149
|
+
expect(
|
|
150
|
+
spec.components.schemas.OperationResponse.properties.suggestedActions,
|
|
151
|
+
).toBeDefined();
|
|
152
|
+
expect(
|
|
153
|
+
spec.components.schemas.OperationResponse.properties.nextSteps,
|
|
154
|
+
).toBeDefined();
|
|
155
|
+
expect(
|
|
156
|
+
spec.paths["/api/gpt/query/a"].get.responses["200"].content[
|
|
157
|
+
"application/json"
|
|
158
|
+
].schema.$ref,
|
|
159
|
+
).toBe("#/components/schemas/OperationResponse");
|
|
160
|
+
});
|
|
161
|
+
|
|
162
|
+
test("securityScheme override for oauth2 flow", () => {
|
|
163
|
+
const spec = generateOpenApi({
|
|
164
|
+
registry: registry({ a: makeOp("a") }),
|
|
165
|
+
info,
|
|
166
|
+
servers,
|
|
167
|
+
basePath,
|
|
168
|
+
securityScheme: {
|
|
169
|
+
type: "oauth2",
|
|
170
|
+
flows: {
|
|
171
|
+
authorizationCode: {
|
|
172
|
+
authorizationUrl: "https://example.com/oauth/authorize",
|
|
173
|
+
tokenUrl: "https://example.com/oauth/token",
|
|
174
|
+
scopes: {},
|
|
175
|
+
},
|
|
176
|
+
},
|
|
177
|
+
},
|
|
178
|
+
}) as any;
|
|
179
|
+
expect(spec.components.securitySchemes.bearerAuth).toEqual({
|
|
180
|
+
type: "oauth2",
|
|
181
|
+
flows: {
|
|
182
|
+
authorizationCode: {
|
|
183
|
+
authorizationUrl: "https://example.com/oauth/authorize",
|
|
184
|
+
tokenUrl: "https://example.com/oauth/token",
|
|
185
|
+
scopes: {},
|
|
186
|
+
},
|
|
187
|
+
},
|
|
188
|
+
});
|
|
189
|
+
});
|
|
190
|
+
|
|
109
191
|
test("custom bearerSchemeName", () => {
|
|
110
192
|
const spec = generateOpenApi({
|
|
111
193
|
registry: registry({ a: makeOp("a") }),
|
|
@@ -134,6 +216,7 @@ describe("generateOpenApi pathStyle: 'per-op'", () => {
|
|
|
134
216
|
const spec = generateOpenApi({
|
|
135
217
|
...opts,
|
|
136
218
|
registry: registry({ a: makeOp("a", { auth: "required" }) }),
|
|
219
|
+
includeDiscoveryEndpoints: false,
|
|
137
220
|
}) as any;
|
|
138
221
|
expect(Object.keys(spec.paths)).toEqual(["/api/gpt/query/a"]);
|
|
139
222
|
expect(spec.paths["/api/gpt/query/a"].get.security).toEqual([
|
|
@@ -145,6 +228,7 @@ describe("generateOpenApi pathStyle: 'per-op'", () => {
|
|
|
145
228
|
const spec = generateOpenApi({
|
|
146
229
|
...opts,
|
|
147
230
|
registry: registry({ a: makeOp("a", { auth: "none" }) }),
|
|
231
|
+
includeDiscoveryEndpoints: false,
|
|
148
232
|
}) as any;
|
|
149
233
|
expect(Object.keys(spec.paths)).toEqual(["/api/gpt/public/query/a"]);
|
|
150
234
|
expect(spec.paths["/api/gpt/public/query/a"].get.security).toEqual([]);
|
|
@@ -154,6 +238,7 @@ describe("generateOpenApi pathStyle: 'per-op'", () => {
|
|
|
154
238
|
const spec = generateOpenApi({
|
|
155
239
|
...opts,
|
|
156
240
|
registry: registry({ a: makeOp("a", { auth: "optional" }) }),
|
|
241
|
+
includeDiscoveryEndpoints: false,
|
|
157
242
|
}) as any;
|
|
158
243
|
const ks = Object.keys(spec.paths).sort();
|
|
159
244
|
expect(ks).toEqual(["/api/gpt/public/query/a", "/api/gpt/query/a"]);
|
|
@@ -190,6 +275,7 @@ describe("generateOpenApi pathStyle: 'parametric' (default)", () => {
|
|
|
190
275
|
info,
|
|
191
276
|
servers,
|
|
192
277
|
basePath,
|
|
278
|
+
includeDiscoveryEndpoints: false,
|
|
193
279
|
}) as any;
|
|
194
280
|
const ks = Object.keys(spec.paths);
|
|
195
281
|
expect(ks).toEqual(["/api/gpt/query/{operation}"]);
|
|
@@ -209,6 +295,7 @@ describe("generateOpenApi pathStyle: 'parametric' (default)", () => {
|
|
|
209
295
|
info,
|
|
210
296
|
servers,
|
|
211
297
|
basePath,
|
|
298
|
+
includeDiscoveryEndpoints: false,
|
|
212
299
|
}) as any;
|
|
213
300
|
const ks = Object.keys(spec.paths).sort();
|
|
214
301
|
expect(ks).toEqual([
|
package/src/openapi.ts
CHANGED
|
@@ -17,8 +17,32 @@ export interface GenerateOpenApiConfig {
|
|
|
17
17
|
servers: OpenApiServer[];
|
|
18
18
|
/** Mount path prefix, e.g. "/api/gpt". Omit trailing slash. Defaults to "". */
|
|
19
19
|
basePath?: string;
|
|
20
|
-
/** Name of the
|
|
20
|
+
/** Name of the security scheme entry under components.securitySchemes. Defaults to "bearerAuth". */
|
|
21
21
|
bearerSchemeName?: string;
|
|
22
|
+
/**
|
|
23
|
+
* Full security scheme object to place under components.securitySchemes.
|
|
24
|
+
* Defaults to `{ type: "http", scheme: "bearer" }`. Pass an oauth2 flow
|
|
25
|
+
* object to match ChatGPT Custom GPT OAuth requirements:
|
|
26
|
+
*
|
|
27
|
+
* securityScheme: {
|
|
28
|
+
* type: "oauth2",
|
|
29
|
+
* flows: {
|
|
30
|
+
* authorizationCode: {
|
|
31
|
+
* authorizationUrl: "https://example.com/oauth/authorize",
|
|
32
|
+
* tokenUrl: "https://example.com/oauth/token",
|
|
33
|
+
* scopes: {},
|
|
34
|
+
* },
|
|
35
|
+
* },
|
|
36
|
+
* }
|
|
37
|
+
*/
|
|
38
|
+
securityScheme?: Record<string, unknown>;
|
|
39
|
+
/**
|
|
40
|
+
* Include the discovery endpoints (`GET /operations` and
|
|
41
|
+
* `GET /operations/{name}`) in the generated spec. Default true — the
|
|
42
|
+
* GPT relies on these to learn available operations and their input
|
|
43
|
+
* schemas before invoking one.
|
|
44
|
+
*/
|
|
45
|
+
includeDiscoveryEndpoints?: boolean;
|
|
22
46
|
/** When true, adds an info note about the $variables encoding (default true). */
|
|
23
47
|
describeVariables?: boolean;
|
|
24
48
|
/**
|
|
@@ -86,6 +110,8 @@ export function generateOpenApi(config: GenerateOpenApiConfig): object {
|
|
|
86
110
|
servers,
|
|
87
111
|
basePath = "",
|
|
88
112
|
bearerSchemeName = "bearerAuth",
|
|
113
|
+
securityScheme = { type: "http", scheme: "bearer" },
|
|
114
|
+
includeDiscoveryEndpoints = true,
|
|
89
115
|
describeVariables = true,
|
|
90
116
|
includeDescription = false,
|
|
91
117
|
maxDescriptionLength = 300,
|
|
@@ -129,21 +155,7 @@ export function generateOpenApi(config: GenerateOpenApiConfig): object {
|
|
|
129
155
|
description: "Successful response.",
|
|
130
156
|
content: {
|
|
131
157
|
"application/json": {
|
|
132
|
-
schema: {
|
|
133
|
-
type: "object",
|
|
134
|
-
properties: {
|
|
135
|
-
data: { type: "object" },
|
|
136
|
-
suggestedActions: {
|
|
137
|
-
type: "array",
|
|
138
|
-
items: { type: "object" },
|
|
139
|
-
},
|
|
140
|
-
nextSteps: { type: "string" },
|
|
141
|
-
operations: {
|
|
142
|
-
type: "array",
|
|
143
|
-
items: { type: "object" },
|
|
144
|
-
},
|
|
145
|
-
},
|
|
146
|
-
},
|
|
158
|
+
schema: { $ref: "#/components/schemas/OperationResponse" },
|
|
147
159
|
},
|
|
148
160
|
},
|
|
149
161
|
},
|
|
@@ -151,19 +163,7 @@ export function generateOpenApi(config: GenerateOpenApiConfig): object {
|
|
|
151
163
|
description: "Validation or execution error.",
|
|
152
164
|
content: {
|
|
153
165
|
"application/json": {
|
|
154
|
-
schema: {
|
|
155
|
-
type: "object",
|
|
156
|
-
properties: {
|
|
157
|
-
errors: {
|
|
158
|
-
type: "array",
|
|
159
|
-
items: {
|
|
160
|
-
type: "object",
|
|
161
|
-
properties: { message: { type: "string" } },
|
|
162
|
-
},
|
|
163
|
-
},
|
|
164
|
-
operationDetail: { type: "object" },
|
|
165
|
-
},
|
|
166
|
-
},
|
|
166
|
+
schema: { $ref: "#/components/schemas/OperationResponse" },
|
|
167
167
|
},
|
|
168
168
|
},
|
|
169
169
|
},
|
|
@@ -243,21 +243,224 @@ export function generateOpenApi(config: GenerateOpenApiConfig): object {
|
|
|
243
243
|
}
|
|
244
244
|
}
|
|
245
245
|
|
|
246
|
+
if (includeDiscoveryEndpoints) {
|
|
247
|
+
emitDiscoveryEndpoints(paths, basePath, noSec, successResponse);
|
|
248
|
+
}
|
|
249
|
+
|
|
246
250
|
return {
|
|
247
251
|
openapi: "3.1.0",
|
|
248
252
|
info,
|
|
249
253
|
servers,
|
|
250
254
|
paths,
|
|
251
255
|
components: {
|
|
252
|
-
schemas: {
|
|
256
|
+
schemas: {
|
|
257
|
+
OperationResponse: operationResponseSchema,
|
|
258
|
+
},
|
|
253
259
|
securitySchemes: {
|
|
254
|
-
[bearerSchemeName]:
|
|
255
|
-
|
|
256
|
-
|
|
260
|
+
[bearerSchemeName]: securityScheme,
|
|
261
|
+
},
|
|
262
|
+
},
|
|
263
|
+
};
|
|
264
|
+
}
|
|
265
|
+
|
|
266
|
+
const operationResponseSchema = {
|
|
267
|
+
type: "object",
|
|
268
|
+
properties: {
|
|
269
|
+
data: { type: "object", description: "Operation result data" },
|
|
270
|
+
errors: {
|
|
271
|
+
type: "array",
|
|
272
|
+
description: "Included on error responses.",
|
|
273
|
+
items: {
|
|
274
|
+
type: "object",
|
|
275
|
+
properties: { message: { type: "string" } },
|
|
276
|
+
},
|
|
277
|
+
},
|
|
278
|
+
operations: {
|
|
279
|
+
type: "array",
|
|
280
|
+
description:
|
|
281
|
+
"All available operations (always present in every response).",
|
|
282
|
+
items: {
|
|
283
|
+
type: "object",
|
|
284
|
+
properties: {
|
|
285
|
+
id: { type: "string" },
|
|
286
|
+
type: { type: "string", enum: ["query", "mutation"] },
|
|
287
|
+
description: { type: "string" },
|
|
288
|
+
auth: { type: "string", enum: ["none", "optional", "required"] },
|
|
289
|
+
},
|
|
290
|
+
},
|
|
291
|
+
},
|
|
292
|
+
suggestedActions: {
|
|
293
|
+
type: "array",
|
|
294
|
+
description:
|
|
295
|
+
"Context-aware suggested next operations with pre-filled variables.",
|
|
296
|
+
items: {
|
|
297
|
+
type: "object",
|
|
298
|
+
properties: {
|
|
299
|
+
id: { type: "string" },
|
|
300
|
+
type: { type: "string", enum: ["query", "mutation"] },
|
|
301
|
+
description: { type: "string" },
|
|
302
|
+
variables: { type: "object" },
|
|
303
|
+
$variables: {
|
|
304
|
+
type: "string",
|
|
305
|
+
description: "Variables pre-encoded as a string, ready to reuse.",
|
|
306
|
+
},
|
|
307
|
+
input: {
|
|
308
|
+
type: "object",
|
|
309
|
+
description: "JSON Schema for this operation's variables",
|
|
310
|
+
},
|
|
257
311
|
},
|
|
258
312
|
},
|
|
259
313
|
},
|
|
314
|
+
display: {
|
|
315
|
+
type: "string",
|
|
316
|
+
description:
|
|
317
|
+
"Pre-rendered text in the user's locale. Suggested wording — adapt tone freely but keep amounts and names accurate.",
|
|
318
|
+
},
|
|
319
|
+
nextSteps: {
|
|
320
|
+
type: "string",
|
|
321
|
+
description:
|
|
322
|
+
"Contextual instructions for the assistant. Follow these exactly.",
|
|
323
|
+
},
|
|
324
|
+
operationDetail: {
|
|
325
|
+
type: "object",
|
|
326
|
+
description:
|
|
327
|
+
"Included on error responses. Contains the operation's input schema and instruction so you can fix your request and retry.",
|
|
328
|
+
properties: {
|
|
329
|
+
instruction: { type: "string" },
|
|
330
|
+
input: { type: "object" },
|
|
331
|
+
},
|
|
332
|
+
},
|
|
333
|
+
responseSchema: {
|
|
334
|
+
type: "object",
|
|
335
|
+
description:
|
|
336
|
+
"JSON Schema for the response data. Included on the start response when configured.",
|
|
337
|
+
},
|
|
338
|
+
},
|
|
339
|
+
};
|
|
340
|
+
|
|
341
|
+
function emitDiscoveryEndpoints(
|
|
342
|
+
paths: Record<string, PathItem>,
|
|
343
|
+
basePath: string,
|
|
344
|
+
noSec: Sec,
|
|
345
|
+
successResponse: Record<string, unknown>,
|
|
346
|
+
): void {
|
|
347
|
+
paths[`${basePath}/operations`] = {
|
|
348
|
+
get: {
|
|
349
|
+
operationId: "listOperations",
|
|
350
|
+
summary: "Discover available operations",
|
|
351
|
+
security: noSec,
|
|
352
|
+
parameters: [
|
|
353
|
+
{
|
|
354
|
+
name: "search",
|
|
355
|
+
in: "query",
|
|
356
|
+
required: false,
|
|
357
|
+
description: "Filter operations by keyword in id or description.",
|
|
358
|
+
schema: { type: "string" },
|
|
359
|
+
},
|
|
360
|
+
{
|
|
361
|
+
name: "type",
|
|
362
|
+
in: "query",
|
|
363
|
+
required: false,
|
|
364
|
+
description: "Filter by operation type.",
|
|
365
|
+
schema: { type: "string", enum: ["query", "mutation"] },
|
|
366
|
+
},
|
|
367
|
+
],
|
|
368
|
+
responses: {
|
|
369
|
+
"200": {
|
|
370
|
+
description: "List of available operations",
|
|
371
|
+
content: {
|
|
372
|
+
"application/json": {
|
|
373
|
+
schema: {
|
|
374
|
+
type: "object",
|
|
375
|
+
properties: {
|
|
376
|
+
operations: {
|
|
377
|
+
type: "array",
|
|
378
|
+
items: {
|
|
379
|
+
type: "object",
|
|
380
|
+
properties: {
|
|
381
|
+
id: { type: "string" },
|
|
382
|
+
type: {
|
|
383
|
+
type: "string",
|
|
384
|
+
enum: ["query", "mutation"],
|
|
385
|
+
},
|
|
386
|
+
description: { type: "string" },
|
|
387
|
+
auth: {
|
|
388
|
+
type: "string",
|
|
389
|
+
enum: ["none", "optional", "required"],
|
|
390
|
+
},
|
|
391
|
+
},
|
|
392
|
+
},
|
|
393
|
+
},
|
|
394
|
+
},
|
|
395
|
+
},
|
|
396
|
+
},
|
|
397
|
+
},
|
|
398
|
+
},
|
|
399
|
+
},
|
|
400
|
+
} as Operation,
|
|
401
|
+
};
|
|
402
|
+
|
|
403
|
+
paths[`${basePath}/operations/{name}`] = {
|
|
404
|
+
get: {
|
|
405
|
+
operationId: "getOperationDetail",
|
|
406
|
+
summary: "Get full details for a specific operation",
|
|
407
|
+
security: noSec,
|
|
408
|
+
parameters: [
|
|
409
|
+
{
|
|
410
|
+
name: "name",
|
|
411
|
+
in: "path",
|
|
412
|
+
required: true,
|
|
413
|
+
description: "Operation slug.",
|
|
414
|
+
schema: { type: "string" },
|
|
415
|
+
},
|
|
416
|
+
],
|
|
417
|
+
responses: {
|
|
418
|
+
"200": {
|
|
419
|
+
description: "Operation detail",
|
|
420
|
+
content: {
|
|
421
|
+
"application/json": {
|
|
422
|
+
schema: {
|
|
423
|
+
type: "object",
|
|
424
|
+
properties: {
|
|
425
|
+
id: { type: "string" },
|
|
426
|
+
type: { type: "string", enum: ["query", "mutation"] },
|
|
427
|
+
description: { type: "string" },
|
|
428
|
+
instruction: { type: "string" },
|
|
429
|
+
input: { type: "object" },
|
|
430
|
+
response: { type: "object" },
|
|
431
|
+
auth: {
|
|
432
|
+
type: "string",
|
|
433
|
+
enum: ["none", "optional", "required"],
|
|
434
|
+
},
|
|
435
|
+
operations: {
|
|
436
|
+
type: "array",
|
|
437
|
+
description:
|
|
438
|
+
"Present when includeOperationsInDetail is enabled on gptRoutes.",
|
|
439
|
+
items: {
|
|
440
|
+
type: "object",
|
|
441
|
+
properties: {
|
|
442
|
+
id: { type: "string" },
|
|
443
|
+
type: { type: "string", enum: ["query", "mutation"] },
|
|
444
|
+
description: { type: "string" },
|
|
445
|
+
auth: {
|
|
446
|
+
type: "string",
|
|
447
|
+
enum: ["none", "optional", "required"],
|
|
448
|
+
},
|
|
449
|
+
},
|
|
450
|
+
},
|
|
451
|
+
},
|
|
452
|
+
},
|
|
453
|
+
},
|
|
454
|
+
},
|
|
455
|
+
},
|
|
456
|
+
},
|
|
457
|
+
"404": {
|
|
458
|
+
description: "Unknown operation",
|
|
459
|
+
},
|
|
460
|
+
},
|
|
461
|
+
} as Operation,
|
|
260
462
|
};
|
|
463
|
+
void successResponse;
|
|
261
464
|
}
|
|
262
465
|
|
|
263
466
|
function emitParametric(
|