@donghanh/hono 0.3.2 → 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 +223 -64
- package/src/openapi.ts +426 -73
package/package.json
CHANGED
package/src/openapi.test.ts
CHANGED
|
@@ -31,8 +31,8 @@ const info = { title: "Test API", version: "1.0.0" };
|
|
|
31
31
|
const servers = [{ url: "https://api.example.com" }];
|
|
32
32
|
const basePath = "/api/gpt";
|
|
33
33
|
|
|
34
|
-
describe("generateOpenApi", () => {
|
|
35
|
-
test("emits 3.1.0 spec with info + servers +
|
|
34
|
+
describe("generateOpenApi common", () => {
|
|
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,14 +46,177 @@ describe("generateOpenApi", () => {
|
|
|
46
46
|
type: "http",
|
|
47
47
|
scheme: "bearer",
|
|
48
48
|
});
|
|
49
|
+
// components.schemas always includes OperationResponse (validator requires object)
|
|
50
|
+
expect(typeof spec.components.schemas).toBe("object");
|
|
51
|
+
expect(spec.components.schemas.OperationResponse).toBeDefined();
|
|
49
52
|
});
|
|
50
53
|
|
|
51
|
-
test("
|
|
54
|
+
test("includeDescription is off by default — no description field", () => {
|
|
52
55
|
const spec = generateOpenApi({
|
|
53
|
-
registry: registry({ a: makeOp("a"
|
|
56
|
+
registry: registry({ a: makeOp("a") }),
|
|
57
|
+
info,
|
|
58
|
+
servers,
|
|
59
|
+
basePath,
|
|
60
|
+
pathStyle: "per-op",
|
|
61
|
+
}) as any;
|
|
62
|
+
const entry = spec.paths["/api/gpt/query/a"].get;
|
|
63
|
+
expect(entry.description).toBeUndefined();
|
|
64
|
+
expect(entry.summary).toBe("a desc");
|
|
65
|
+
});
|
|
66
|
+
|
|
67
|
+
test("includeDescription: true emits description built from desc+instruction", () => {
|
|
68
|
+
const spec = generateOpenApi({
|
|
69
|
+
registry: registry({ a: makeOp("a") }),
|
|
70
|
+
info,
|
|
71
|
+
servers,
|
|
72
|
+
basePath,
|
|
73
|
+
pathStyle: "per-op",
|
|
74
|
+
includeDescription: true,
|
|
75
|
+
}) as any;
|
|
76
|
+
const d = spec.paths["/api/gpt/query/a"].get.description as string;
|
|
77
|
+
expect(d).toContain("a desc");
|
|
78
|
+
expect(d).toContain("call a");
|
|
79
|
+
});
|
|
80
|
+
|
|
81
|
+
test("description truncated at maxDescriptionLength when included", () => {
|
|
82
|
+
const spec = generateOpenApi({
|
|
83
|
+
registry: registry({
|
|
84
|
+
a: makeOp("a", { instruction: "x".repeat(500) }),
|
|
85
|
+
}),
|
|
86
|
+
info,
|
|
87
|
+
servers,
|
|
88
|
+
basePath,
|
|
89
|
+
pathStyle: "per-op",
|
|
90
|
+
includeDescription: true,
|
|
91
|
+
}) as any;
|
|
92
|
+
const d = spec.paths["/api/gpt/query/a"].get.description as string;
|
|
93
|
+
expect(d.length).toBeLessThanOrEqual(300);
|
|
94
|
+
expect(d.endsWith("…")).toBe(true);
|
|
95
|
+
});
|
|
96
|
+
|
|
97
|
+
test("summary capped at 120 chars", () => {
|
|
98
|
+
const spec = generateOpenApi({
|
|
99
|
+
registry: registry({
|
|
100
|
+
a: makeOp("a", { description: "y".repeat(200) }),
|
|
101
|
+
}),
|
|
102
|
+
info,
|
|
103
|
+
servers,
|
|
104
|
+
basePath,
|
|
105
|
+
pathStyle: "per-op",
|
|
106
|
+
}) as any;
|
|
107
|
+
const s = spec.paths["/api/gpt/query/a"].get.summary as string;
|
|
108
|
+
expect(s.length).toBeLessThanOrEqual(120);
|
|
109
|
+
});
|
|
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") }),
|
|
54
165
|
info,
|
|
55
166
|
servers,
|
|
56
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
|
+
|
|
191
|
+
test("custom bearerSchemeName", () => {
|
|
192
|
+
const spec = generateOpenApi({
|
|
193
|
+
registry: registry({ a: makeOp("a") }),
|
|
194
|
+
info,
|
|
195
|
+
servers,
|
|
196
|
+
basePath,
|
|
197
|
+
pathStyle: "per-op",
|
|
198
|
+
bearerSchemeName: "oauthToken",
|
|
199
|
+
}) as any;
|
|
200
|
+
expect(spec.components.securitySchemes.oauthToken).toBeDefined();
|
|
201
|
+
expect(spec.paths["/api/gpt/query/a"].get.security).toEqual([
|
|
202
|
+
{ oauthToken: [] },
|
|
203
|
+
]);
|
|
204
|
+
});
|
|
205
|
+
});
|
|
206
|
+
|
|
207
|
+
describe("generateOpenApi pathStyle: 'per-op'", () => {
|
|
208
|
+
const opts = {
|
|
209
|
+
info,
|
|
210
|
+
servers,
|
|
211
|
+
basePath,
|
|
212
|
+
pathStyle: "per-op" as const,
|
|
213
|
+
};
|
|
214
|
+
|
|
215
|
+
test("auth=required emits default path only with bearerAuth", () => {
|
|
216
|
+
const spec = generateOpenApi({
|
|
217
|
+
...opts,
|
|
218
|
+
registry: registry({ a: makeOp("a", { auth: "required" }) }),
|
|
219
|
+
includeDiscoveryEndpoints: false,
|
|
57
220
|
}) as any;
|
|
58
221
|
expect(Object.keys(spec.paths)).toEqual(["/api/gpt/query/a"]);
|
|
59
222
|
expect(spec.paths["/api/gpt/query/a"].get.security).toEqual([
|
|
@@ -63,36 +226,28 @@ describe("generateOpenApi", () => {
|
|
|
63
226
|
|
|
64
227
|
test("auth=none emits /public path with empty security", () => {
|
|
65
228
|
const spec = generateOpenApi({
|
|
229
|
+
...opts,
|
|
66
230
|
registry: registry({ a: makeOp("a", { auth: "none" }) }),
|
|
67
|
-
|
|
68
|
-
servers,
|
|
69
|
-
basePath,
|
|
231
|
+
includeDiscoveryEndpoints: false,
|
|
70
232
|
}) as any;
|
|
71
233
|
expect(Object.keys(spec.paths)).toEqual(["/api/gpt/public/query/a"]);
|
|
72
234
|
expect(spec.paths["/api/gpt/public/query/a"].get.security).toEqual([]);
|
|
73
235
|
});
|
|
74
236
|
|
|
75
|
-
test("auth=optional emits
|
|
237
|
+
test("auth=optional emits both default and /public paths", () => {
|
|
76
238
|
const spec = generateOpenApi({
|
|
239
|
+
...opts,
|
|
77
240
|
registry: registry({ a: makeOp("a", { auth: "optional" }) }),
|
|
78
|
-
|
|
79
|
-
servers,
|
|
80
|
-
basePath,
|
|
241
|
+
includeDiscoveryEndpoints: false,
|
|
81
242
|
}) as any;
|
|
82
243
|
const ks = Object.keys(spec.paths).sort();
|
|
83
244
|
expect(ks).toEqual(["/api/gpt/public/query/a", "/api/gpt/query/a"]);
|
|
84
|
-
expect(spec.paths["/api/gpt/query/a"].get.security).toEqual([
|
|
85
|
-
{ bearerAuth: [] },
|
|
86
|
-
]);
|
|
87
|
-
expect(spec.paths["/api/gpt/public/query/a"].get.security).toEqual([]);
|
|
88
245
|
});
|
|
89
246
|
|
|
90
247
|
test("mutation emits POST with requestBody", () => {
|
|
91
248
|
const spec = generateOpenApi({
|
|
249
|
+
...opts,
|
|
92
250
|
registry: registry({ m: makeOp("m", { type: "mutation" }) }),
|
|
93
|
-
info,
|
|
94
|
-
servers,
|
|
95
|
-
basePath,
|
|
96
251
|
}) as any;
|
|
97
252
|
const entry = spec.paths["/api/gpt/mutate/m"];
|
|
98
253
|
expect(entry.post.requestBody).toBeDefined();
|
|
@@ -101,96 +256,100 @@ describe("generateOpenApi", () => {
|
|
|
101
256
|
|
|
102
257
|
test("query has $variables parameter", () => {
|
|
103
258
|
const spec = generateOpenApi({
|
|
259
|
+
...opts,
|
|
104
260
|
registry: registry({ q: makeOp("q") }),
|
|
105
|
-
info,
|
|
106
|
-
servers,
|
|
107
|
-
basePath,
|
|
108
261
|
}) as any;
|
|
109
262
|
const p = spec.paths["/api/gpt/query/q"].get.parameters;
|
|
110
263
|
expect(p).toHaveLength(1);
|
|
111
264
|
expect(p[0].name).toBe("$variables");
|
|
112
|
-
expect(p[0].in).toBe("query");
|
|
113
|
-
});
|
|
114
|
-
|
|
115
|
-
test("description combines op description + instruction", () => {
|
|
116
|
-
const spec = generateOpenApi({
|
|
117
|
-
registry: registry({ a: makeOp("a") }),
|
|
118
|
-
info,
|
|
119
|
-
servers,
|
|
120
|
-
basePath,
|
|
121
|
-
}) as any;
|
|
122
|
-
const op = spec.paths["/api/gpt/query/a"].get;
|
|
123
|
-
expect(op.summary).toBe("a desc");
|
|
124
|
-
expect(op.description).toContain("a desc");
|
|
125
|
-
expect(op.description).toContain("call a");
|
|
126
265
|
});
|
|
266
|
+
});
|
|
127
267
|
|
|
128
|
-
|
|
268
|
+
describe("generateOpenApi pathStyle: 'parametric' (default)", () => {
|
|
269
|
+
test("collapses all query ops under one /query/{operation} path with enum", () => {
|
|
129
270
|
const spec = generateOpenApi({
|
|
130
271
|
registry: registry({
|
|
131
|
-
a: makeOp("a", { auth: "
|
|
272
|
+
a: makeOp("a", { auth: "required" }),
|
|
273
|
+
b: makeOp("b", { auth: "required" }),
|
|
132
274
|
}),
|
|
133
275
|
info,
|
|
134
276
|
servers,
|
|
135
277
|
basePath,
|
|
278
|
+
includeDiscoveryEndpoints: false,
|
|
136
279
|
}) as any;
|
|
137
|
-
const
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
expect(
|
|
280
|
+
const ks = Object.keys(spec.paths);
|
|
281
|
+
expect(ks).toEqual(["/api/gpt/query/{operation}"]);
|
|
282
|
+
const opParam = spec.paths["/api/gpt/query/{operation}"].get.parameters[0];
|
|
283
|
+
expect(opParam.name).toBe("operation");
|
|
284
|
+
expect(opParam.in).toBe("path");
|
|
285
|
+
expect(opParam.schema.enum).toEqual(["a", "b"]);
|
|
141
286
|
});
|
|
142
287
|
|
|
143
|
-
test("
|
|
288
|
+
test("emits /public/{operation} when any op is auth=none or optional", () => {
|
|
144
289
|
const spec = generateOpenApi({
|
|
145
290
|
registry: registry({
|
|
146
291
|
priv: makeOp("priv", { auth: "required" }),
|
|
147
|
-
mixed: makeOp("mixed", { auth: "optional" }),
|
|
148
292
|
pub: makeOp("pub", { auth: "none" }),
|
|
293
|
+
both: makeOp("both", { auth: "optional" }),
|
|
149
294
|
}),
|
|
150
295
|
info,
|
|
151
296
|
servers,
|
|
152
297
|
basePath,
|
|
298
|
+
includeDiscoveryEndpoints: false,
|
|
153
299
|
}) as any;
|
|
154
300
|
const ks = Object.keys(spec.paths).sort();
|
|
155
301
|
expect(ks).toEqual([
|
|
156
|
-
"/api/gpt/public/query/
|
|
157
|
-
"/api/gpt/
|
|
158
|
-
"/api/gpt/query/mixed",
|
|
159
|
-
"/api/gpt/query/priv",
|
|
302
|
+
"/api/gpt/public/query/{operation}",
|
|
303
|
+
"/api/gpt/query/{operation}",
|
|
160
304
|
]);
|
|
305
|
+
// Default enum contains authed ops: required + optional (not "none")
|
|
306
|
+
expect(
|
|
307
|
+
spec.paths["/api/gpt/query/{operation}"].get.parameters[0].schema.enum,
|
|
308
|
+
).toEqual(["priv", "both"]);
|
|
309
|
+
// Public enum contains guest-callable ops: none + optional (not "required")
|
|
310
|
+
expect(
|
|
311
|
+
spec.paths["/api/gpt/public/query/{operation}"].get.parameters[0].schema
|
|
312
|
+
.enum,
|
|
313
|
+
).toEqual(["pub", "both"]);
|
|
161
314
|
});
|
|
162
315
|
|
|
163
|
-
test("
|
|
316
|
+
test("separate /mutate/{operation} path for mutations", () => {
|
|
164
317
|
const spec = generateOpenApi({
|
|
165
318
|
registry: registry({
|
|
166
|
-
|
|
167
|
-
b: makeOp("b", { auth: "none", type: "mutation" }),
|
|
168
|
-
c: makeOp("c", { auth: "optional" }),
|
|
319
|
+
m: makeOp("m", { type: "mutation" }),
|
|
169
320
|
}),
|
|
170
321
|
info,
|
|
171
322
|
servers,
|
|
172
323
|
basePath,
|
|
173
|
-
includeSiblingsInDescription: true,
|
|
174
324
|
}) as any;
|
|
175
|
-
|
|
176
|
-
expect(
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
expect(description).toContain("`b` (mutation, auth: none) — b desc");
|
|
180
|
-
expect(description).toContain("`c` (query, auth: optional) — c desc");
|
|
325
|
+
expect(spec.paths["/api/gpt/mutate/{operation}"]).toBeDefined();
|
|
326
|
+
expect(
|
|
327
|
+
spec.paths["/api/gpt/mutate/{operation}"].post.requestBody,
|
|
328
|
+
).toBeDefined();
|
|
181
329
|
});
|
|
182
330
|
|
|
183
|
-
test("
|
|
331
|
+
test("no description field by default (ChatGPT-safe)", () => {
|
|
184
332
|
const spec = generateOpenApi({
|
|
185
333
|
registry: registry({ a: makeOp("a") }),
|
|
186
334
|
info,
|
|
187
335
|
servers,
|
|
188
336
|
basePath,
|
|
189
|
-
bearerSchemeName: "oauthToken",
|
|
190
337
|
}) as any;
|
|
191
|
-
|
|
192
|
-
expect(
|
|
193
|
-
|
|
194
|
-
|
|
338
|
+
const entry = spec.paths["/api/gpt/query/{operation}"].get;
|
|
339
|
+
expect(entry.description).toBeUndefined();
|
|
340
|
+
});
|
|
341
|
+
|
|
342
|
+
test("includeDescription: true emits a short description", () => {
|
|
343
|
+
const spec = generateOpenApi({
|
|
344
|
+
registry: registry({ a: makeOp("a") }),
|
|
345
|
+
info,
|
|
346
|
+
servers,
|
|
347
|
+
basePath,
|
|
348
|
+
includeDescription: true,
|
|
349
|
+
}) as any;
|
|
350
|
+
const d = spec.paths["/api/gpt/query/{operation}"].get
|
|
351
|
+
.description as string;
|
|
352
|
+
expect(typeof d).toBe("string");
|
|
353
|
+
expect(d.length).toBeLessThanOrEqual(300);
|
|
195
354
|
});
|
|
196
355
|
});
|
package/src/openapi.ts
CHANGED
|
@@ -17,16 +17,68 @@ 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
|
/**
|
|
25
|
-
* When true,
|
|
26
|
-
*
|
|
27
|
-
*
|
|
49
|
+
* When true, each path emits a `description` built from the op's
|
|
50
|
+
* description + instruction. Default `false` — only `summary` is emitted,
|
|
51
|
+
* which keeps the spec compact and sidesteps ChatGPT Actions' 300-char
|
|
52
|
+
* description limit. Turn on when you want richer Action instructions in
|
|
53
|
+
* the OAS. (For listing sibling operations, prefer `includeOperationsInDetail`
|
|
54
|
+
* on `gptRoutes` — the GPT fetches `GET /operations/:name` to learn
|
|
55
|
+
* available ops, a cleaner channel than inlining them into OAS.)
|
|
56
|
+
*/
|
|
57
|
+
includeDescription?: boolean;
|
|
58
|
+
/**
|
|
59
|
+
* Max length for each path's OpenAPI `description` when emitted. ChatGPT
|
|
60
|
+
* Actions rejects descriptions over 300 characters, so the default is 300.
|
|
61
|
+
* No effect when `includeDescription` is false.
|
|
28
62
|
*/
|
|
29
|
-
|
|
63
|
+
maxDescriptionLength?: number;
|
|
64
|
+
/**
|
|
65
|
+
* How to lay out paths:
|
|
66
|
+
* - "parametric" (default) — single path with `{operation}` as a path param,
|
|
67
|
+
* matching gptRoutes' route shape (`/query/:operation`). 2–4 paths total
|
|
68
|
+
* regardless of registry size; the model picks the op by filling the
|
|
69
|
+
* `operation` param. Mirrors the existing REST shape and matches the
|
|
70
|
+
* convention most donghanh apps already use in their ChatGPT Action config.
|
|
71
|
+
* - "per-op" — one OAS path per operation, e.g. `/query/start`,
|
|
72
|
+
* `/public/query/check-offer`. Each op gets its own summary + description,
|
|
73
|
+
* so ChatGPT Actions discovers them as separate actions. Larger spec;
|
|
74
|
+
* useful when you want each op to be a discrete ChatGPT Action.
|
|
75
|
+
*/
|
|
76
|
+
pathStyle?: "parametric" | "per-op";
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
function truncate(s: string, max: number): string {
|
|
80
|
+
if (s.length <= max) return s;
|
|
81
|
+
return `${s.slice(0, Math.max(0, max - 1))}…`;
|
|
30
82
|
}
|
|
31
83
|
|
|
32
84
|
type Sec = Array<Record<string, string[]>>;
|
|
@@ -58,20 +110,15 @@ export function generateOpenApi(config: GenerateOpenApiConfig): object {
|
|
|
58
110
|
servers,
|
|
59
111
|
basePath = "",
|
|
60
112
|
bearerSchemeName = "bearerAuth",
|
|
113
|
+
securityScheme = { type: "http", scheme: "bearer" },
|
|
114
|
+
includeDiscoveryEndpoints = true,
|
|
61
115
|
describeVariables = true,
|
|
62
|
-
|
|
116
|
+
includeDescription = false,
|
|
117
|
+
maxDescriptionLength = 300,
|
|
118
|
+
pathStyle = "parametric",
|
|
63
119
|
} = config;
|
|
64
120
|
|
|
65
121
|
const ops = registry.list();
|
|
66
|
-
|
|
67
|
-
const siblingsBlock = includeSiblingsInDescription
|
|
68
|
-
? `\n\nOther operations:\n${ops
|
|
69
|
-
.map(
|
|
70
|
-
(o) =>
|
|
71
|
-
`- \`${o.id}\` (${o.type}, auth: ${o.auth ?? "required"}) — ${o.description}`,
|
|
72
|
-
)
|
|
73
|
-
.join("\n")}`
|
|
74
|
-
: "";
|
|
75
122
|
const paths: Record<string, PathItem> = {};
|
|
76
123
|
|
|
77
124
|
const variablesParam = {
|
|
@@ -108,21 +155,7 @@ export function generateOpenApi(config: GenerateOpenApiConfig): object {
|
|
|
108
155
|
description: "Successful response.",
|
|
109
156
|
content: {
|
|
110
157
|
"application/json": {
|
|
111
|
-
schema: {
|
|
112
|
-
type: "object",
|
|
113
|
-
properties: {
|
|
114
|
-
data: { type: "object" },
|
|
115
|
-
suggestedActions: {
|
|
116
|
-
type: "array",
|
|
117
|
-
items: { type: "object" },
|
|
118
|
-
},
|
|
119
|
-
nextSteps: { type: "string" },
|
|
120
|
-
operations: {
|
|
121
|
-
type: "array",
|
|
122
|
-
items: { type: "object" },
|
|
123
|
-
},
|
|
124
|
-
},
|
|
125
|
-
},
|
|
158
|
+
schema: { $ref: "#/components/schemas/OperationResponse" },
|
|
126
159
|
},
|
|
127
160
|
},
|
|
128
161
|
},
|
|
@@ -130,19 +163,7 @@ export function generateOpenApi(config: GenerateOpenApiConfig): object {
|
|
|
130
163
|
description: "Validation or execution error.",
|
|
131
164
|
content: {
|
|
132
165
|
"application/json": {
|
|
133
|
-
schema: {
|
|
134
|
-
type: "object",
|
|
135
|
-
properties: {
|
|
136
|
-
errors: {
|
|
137
|
-
type: "array",
|
|
138
|
-
items: {
|
|
139
|
-
type: "object",
|
|
140
|
-
properties: { message: { type: "string" } },
|
|
141
|
-
},
|
|
142
|
-
},
|
|
143
|
-
operationDetail: { type: "object" },
|
|
144
|
-
},
|
|
145
|
-
},
|
|
166
|
+
schema: { $ref: "#/components/schemas/OperationResponse" },
|
|
146
167
|
},
|
|
147
168
|
},
|
|
148
169
|
},
|
|
@@ -161,29 +182,24 @@ export function generateOpenApi(config: GenerateOpenApiConfig): object {
|
|
|
161
182
|
security: Sec,
|
|
162
183
|
) => {
|
|
163
184
|
const detail = registry.detail(op.id);
|
|
164
|
-
const pascal = op.id
|
|
165
|
-
.split(/[-_]/)
|
|
166
|
-
.map((s) => (s ? s[0].toUpperCase() + s.slice(1) : ""))
|
|
167
|
-
.join("");
|
|
168
185
|
const entry: Operation = {
|
|
169
186
|
operationId: `${method}_${op.id}`.replace(/[^A-Za-z0-9_]/g, "_"),
|
|
170
|
-
summary: op.description,
|
|
171
|
-
description:
|
|
172
|
-
(detail?.instruction
|
|
173
|
-
? `${op.description}\n\n${detail.instruction}`
|
|
174
|
-
: op.description) + siblingsBlock,
|
|
187
|
+
summary: truncate(op.description, 120),
|
|
175
188
|
security,
|
|
176
189
|
responses: successResponse,
|
|
177
190
|
};
|
|
191
|
+
if (includeDescription) {
|
|
192
|
+
const full = detail?.instruction
|
|
193
|
+
? `${op.description}\n\n${detail.instruction}`
|
|
194
|
+
: op.description;
|
|
195
|
+
entry.description = truncate(full, maxDescriptionLength);
|
|
196
|
+
}
|
|
178
197
|
if (method === "get") {
|
|
179
198
|
entry.parameters = [variablesParam];
|
|
180
199
|
} else {
|
|
181
200
|
entry.requestBody = variablesBody;
|
|
182
201
|
}
|
|
183
|
-
// Tag by op type to help OpenAPI UIs group them.
|
|
184
202
|
(entry as Record<string, unknown>).tags = [op.type];
|
|
185
|
-
// Hint: unused `pascal` to keep id stable if we later switch to camelCase.
|
|
186
|
-
void pascal;
|
|
187
203
|
|
|
188
204
|
let item = paths[path];
|
|
189
205
|
if (!item) {
|
|
@@ -196,25 +212,39 @@ export function generateOpenApi(config: GenerateOpenApiConfig): object {
|
|
|
196
212
|
const authedSec: Sec = [{ [bearerSchemeName]: [] }];
|
|
197
213
|
const noSec: Sec = [];
|
|
198
214
|
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
215
|
+
if (pathStyle === "parametric") {
|
|
216
|
+
emitParametric(paths, basePath, authedSec, noSec, ops, {
|
|
217
|
+
includeDescription,
|
|
218
|
+
maxDescriptionLength,
|
|
219
|
+
variablesParam,
|
|
220
|
+
variablesBody,
|
|
221
|
+
successResponse,
|
|
222
|
+
});
|
|
223
|
+
} else {
|
|
224
|
+
for (const op of ops) {
|
|
225
|
+
const method: "get" | "post" = op.type === "query" ? "get" : "post";
|
|
226
|
+
const auth = op.auth ?? "required";
|
|
202
227
|
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
228
|
+
const methodPath = op.type === "query" ? "query" : "mutate";
|
|
229
|
+
const defaultPath = `${basePath}/${methodPath}/${op.id}`;
|
|
230
|
+
const publicPath = `${basePath}/public/${methodPath}/${op.id}`;
|
|
206
231
|
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
232
|
+
if (auth === "none") {
|
|
233
|
+
emit(publicPath, method, op, noSec);
|
|
234
|
+
continue;
|
|
235
|
+
}
|
|
236
|
+
if (auth === "required") {
|
|
237
|
+
emit(defaultPath, method, op, authedSec);
|
|
238
|
+
continue;
|
|
239
|
+
}
|
|
240
|
+
// optional → expose both
|
|
212
241
|
emit(defaultPath, method, op, authedSec);
|
|
213
|
-
|
|
242
|
+
emit(publicPath, method, op, noSec);
|
|
214
243
|
}
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
if (includeDiscoveryEndpoints) {
|
|
247
|
+
emitDiscoveryEndpoints(paths, basePath, noSec, successResponse);
|
|
218
248
|
}
|
|
219
249
|
|
|
220
250
|
return {
|
|
@@ -223,12 +253,335 @@ export function generateOpenApi(config: GenerateOpenApiConfig): object {
|
|
|
223
253
|
servers,
|
|
224
254
|
paths,
|
|
225
255
|
components: {
|
|
256
|
+
schemas: {
|
|
257
|
+
OperationResponse: operationResponseSchema,
|
|
258
|
+
},
|
|
226
259
|
securitySchemes: {
|
|
227
|
-
[bearerSchemeName]:
|
|
228
|
-
|
|
229
|
-
|
|
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"] },
|
|
230
289
|
},
|
|
231
290
|
},
|
|
232
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
|
+
},
|
|
311
|
+
},
|
|
312
|
+
},
|
|
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,
|
|
233
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,
|
|
462
|
+
};
|
|
463
|
+
void successResponse;
|
|
464
|
+
}
|
|
465
|
+
|
|
466
|
+
function emitParametric(
|
|
467
|
+
paths: Record<string, PathItem>,
|
|
468
|
+
basePath: string,
|
|
469
|
+
authedSec: Sec,
|
|
470
|
+
noSec: Sec,
|
|
471
|
+
ops: ReturnType<Registry["list"]>,
|
|
472
|
+
ctx: {
|
|
473
|
+
includeDescription: boolean;
|
|
474
|
+
maxDescriptionLength: number;
|
|
475
|
+
variablesParam: Record<string, unknown>;
|
|
476
|
+
variablesBody: Record<string, unknown>;
|
|
477
|
+
successResponse: Record<string, unknown>;
|
|
478
|
+
},
|
|
479
|
+
): void {
|
|
480
|
+
const queryIds = ops.filter((o) => o.type === "query").map((o) => o.id);
|
|
481
|
+
const mutationIds = ops.filter((o) => o.type === "mutation").map((o) => o.id);
|
|
482
|
+
const authedQueryIds = ops
|
|
483
|
+
.filter((o) => o.type === "query" && (o.auth ?? "required") !== "none")
|
|
484
|
+
.map((o) => o.id);
|
|
485
|
+
const authedMutationIds = ops
|
|
486
|
+
.filter((o) => o.type === "mutation" && (o.auth ?? "required") !== "none")
|
|
487
|
+
.map((o) => o.id);
|
|
488
|
+
const publicQueryIds = ops
|
|
489
|
+
.filter((o) => o.type === "query" && (o.auth ?? "required") !== "required")
|
|
490
|
+
.map((o) => o.id);
|
|
491
|
+
const publicMutationIds = ops
|
|
492
|
+
.filter(
|
|
493
|
+
(o) => o.type === "mutation" && (o.auth ?? "required") !== "required",
|
|
494
|
+
)
|
|
495
|
+
.map((o) => o.id);
|
|
496
|
+
|
|
497
|
+
const opParam = (enumIds: string[]): Record<string, unknown> => ({
|
|
498
|
+
name: "operation",
|
|
499
|
+
in: "path",
|
|
500
|
+
required: true,
|
|
501
|
+
description: `Operation slug. One of: ${enumIds.join(", ")}.`,
|
|
502
|
+
schema: { type: "string", enum: enumIds },
|
|
503
|
+
});
|
|
504
|
+
|
|
505
|
+
const make = (
|
|
506
|
+
opName: string,
|
|
507
|
+
summary: string,
|
|
508
|
+
_method: "get" | "post",
|
|
509
|
+
security: Sec,
|
|
510
|
+
enumIds: string[],
|
|
511
|
+
bodyBased: boolean,
|
|
512
|
+
description: string,
|
|
513
|
+
): Operation => {
|
|
514
|
+
const entry: Operation = {
|
|
515
|
+
operationId: opName,
|
|
516
|
+
summary: truncate(summary, 120),
|
|
517
|
+
security,
|
|
518
|
+
responses: ctx.successResponse as Record<string, unknown>,
|
|
519
|
+
parameters: bodyBased
|
|
520
|
+
? [opParam(enumIds)]
|
|
521
|
+
: [opParam(enumIds), ctx.variablesParam],
|
|
522
|
+
};
|
|
523
|
+
if (ctx.includeDescription) {
|
|
524
|
+
entry.description = truncate(description, ctx.maxDescriptionLength);
|
|
525
|
+
}
|
|
526
|
+
if (bodyBased) entry.requestBody = ctx.variablesBody;
|
|
527
|
+
return entry;
|
|
528
|
+
};
|
|
529
|
+
|
|
530
|
+
if (queryIds.length) {
|
|
531
|
+
if (authedQueryIds.length) {
|
|
532
|
+
paths[`${basePath}/query/{operation}`] = {
|
|
533
|
+
get: make(
|
|
534
|
+
"queryOperation",
|
|
535
|
+
"Execute a query operation",
|
|
536
|
+
"get",
|
|
537
|
+
authedSec,
|
|
538
|
+
authedQueryIds,
|
|
539
|
+
false,
|
|
540
|
+
"Execute a read-only query by name. Pass variables as a JSON or TOON string in $variables.",
|
|
541
|
+
),
|
|
542
|
+
};
|
|
543
|
+
}
|
|
544
|
+
if (publicQueryIds.length) {
|
|
545
|
+
paths[`${basePath}/public/query/{operation}`] = {
|
|
546
|
+
get: make(
|
|
547
|
+
"publicQueryOperation",
|
|
548
|
+
"Execute a public query operation",
|
|
549
|
+
"get",
|
|
550
|
+
noSec,
|
|
551
|
+
publicQueryIds,
|
|
552
|
+
false,
|
|
553
|
+
"Execute a public query by name — no authentication required.",
|
|
554
|
+
),
|
|
555
|
+
};
|
|
556
|
+
}
|
|
557
|
+
}
|
|
558
|
+
|
|
559
|
+
if (mutationIds.length) {
|
|
560
|
+
if (authedMutationIds.length) {
|
|
561
|
+
paths[`${basePath}/mutate/{operation}`] = {
|
|
562
|
+
post: make(
|
|
563
|
+
"mutateOperation",
|
|
564
|
+
"Execute a mutation operation",
|
|
565
|
+
"post",
|
|
566
|
+
authedSec,
|
|
567
|
+
authedMutationIds,
|
|
568
|
+
true,
|
|
569
|
+
"Execute a mutation by name. Pass variables in the JSON body's $variables field.",
|
|
570
|
+
),
|
|
571
|
+
};
|
|
572
|
+
}
|
|
573
|
+
if (publicMutationIds.length) {
|
|
574
|
+
paths[`${basePath}/public/mutate/{operation}`] = {
|
|
575
|
+
post: make(
|
|
576
|
+
"publicMutateOperation",
|
|
577
|
+
"Execute a public mutation operation",
|
|
578
|
+
"post",
|
|
579
|
+
noSec,
|
|
580
|
+
publicMutationIds,
|
|
581
|
+
true,
|
|
582
|
+
"Execute a public mutation by name — no authentication required.",
|
|
583
|
+
),
|
|
584
|
+
};
|
|
585
|
+
}
|
|
586
|
+
}
|
|
234
587
|
}
|