@hectoday/openapi 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/dist/index.d.mts +47 -0
  2. package/dist/index.mjs +134 -0
  3. package/package.json +58 -0
package/dist/index.d.mts ADDED
@@ -0,0 +1,47 @@
1
+ import { RouteDescriptor } from "@hectoday/http";
2
+
3
+ //#region src/index.d.ts
4
+ interface OpenApiConfig {
5
+ info: {
6
+ title: string;
7
+ version: string;
8
+ description?: string;
9
+ license?: {
10
+ name: string;
11
+ url?: string;
12
+ };
13
+ };
14
+ specPath?: string;
15
+ docsPath?: string;
16
+ servers?: Array<{
17
+ url: string;
18
+ description?: string;
19
+ }>;
20
+ tags?: Array<{
21
+ name: string;
22
+ description?: string;
23
+ }>;
24
+ security?: Array<Record<string, string[]>>;
25
+ securitySchemes?: Record<string, SecurityScheme>;
26
+ }
27
+ interface SecurityScheme {
28
+ type: "http" | "apiKey" | "oauth2" | "openIdConnect";
29
+ scheme?: string;
30
+ bearerFormat?: string;
31
+ name?: string;
32
+ in?: "query" | "header" | "cookie";
33
+ description?: string;
34
+ }
35
+ interface OpenApiResult {
36
+ /** Creates a GET route that serves the OpenAPI JSON document. */
37
+ spec: (route: {
38
+ get: (path: string, config: any) => RouteDescriptor;
39
+ }) => RouteDescriptor;
40
+ /** Creates a GET route that serves the Scalar API reference UI. */
41
+ docs: (route: {
42
+ get: (path: string, config: any) => RouteDescriptor;
43
+ }) => RouteDescriptor;
44
+ }
45
+ declare function openapi(routes: RouteDescriptor[], config: OpenApiConfig): OpenApiResult;
46
+ //#endregion
47
+ export { OpenApiConfig, OpenApiResult, SecurityScheme, openapi };
package/dist/index.mjs ADDED
@@ -0,0 +1,134 @@
1
+ import { z } from "zod";
2
+ import { createDocument, extendZodWithOpenApi } from "zod-openapi";
3
+ //#region src/index.ts
4
+ let extended = false;
5
+ function toOpenApiPath(path) {
6
+ return path.replace(/:(\w+)/g, "{$1}");
7
+ }
8
+ const STATUS_TEXT = {
9
+ 100: "Continue",
10
+ 101: "Switching Protocols",
11
+ 102: "Processing",
12
+ 103: "Early Hints",
13
+ 200: "OK",
14
+ 201: "Created",
15
+ 202: "Accepted",
16
+ 203: "Non-Authoritative Information",
17
+ 204: "No Content",
18
+ 205: "Reset Content",
19
+ 206: "Partial Content",
20
+ 207: "Multi-Status",
21
+ 208: "Already Reported",
22
+ 226: "IM Used",
23
+ 300: "Multiple Choices",
24
+ 301: "Moved Permanently",
25
+ 302: "Found",
26
+ 303: "See Other",
27
+ 304: "Not Modified",
28
+ 307: "Temporary Redirect",
29
+ 308: "Permanent Redirect",
30
+ 400: "Bad Request",
31
+ 401: "Unauthorized",
32
+ 402: "Payment Required",
33
+ 403: "Forbidden",
34
+ 404: "Not Found",
35
+ 405: "Method Not Allowed",
36
+ 406: "Not Acceptable",
37
+ 407: "Proxy Authentication Required",
38
+ 408: "Request Timeout",
39
+ 409: "Conflict",
40
+ 410: "Gone",
41
+ 411: "Length Required",
42
+ 412: "Precondition Failed",
43
+ 413: "Content Too Large",
44
+ 414: "URI Too Long",
45
+ 415: "Unsupported Media Type",
46
+ 416: "Range Not Satisfiable",
47
+ 417: "Expectation Failed",
48
+ 418: "I'm a Teapot",
49
+ 421: "Misdirected Request",
50
+ 422: "Unprocessable Entity",
51
+ 423: "Locked",
52
+ 424: "Failed Dependency",
53
+ 425: "Too Early",
54
+ 426: "Upgrade Required",
55
+ 428: "Precondition Required",
56
+ 429: "Too Many Requests",
57
+ 431: "Request Header Fields Too Large",
58
+ 451: "Unavailable For Legal Reasons",
59
+ 500: "Internal Server Error",
60
+ 501: "Not Implemented",
61
+ 502: "Bad Gateway",
62
+ 503: "Service Unavailable",
63
+ 504: "Gateway Timeout",
64
+ 505: "HTTP Version Not Supported",
65
+ 506: "Variant Also Negotiates",
66
+ 507: "Insufficient Storage",
67
+ 508: "Loop Detected",
68
+ 510: "Not Extended",
69
+ 511: "Network Authentication Required"
70
+ };
71
+ function scalarHtml(specUrl) {
72
+ return `<!doctype html>
73
+ <html>
74
+ <head>
75
+ <title>API Reference</title>
76
+ <meta charset="utf-8" />
77
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
78
+ </head>
79
+ <body>
80
+ <script id="api-reference" data-url="${specUrl}"><\/script>
81
+ <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"><\/script>
82
+ </body>
83
+ </html>`;
84
+ }
85
+ function openapi(routes, config) {
86
+ if (!extended) {
87
+ extendZodWithOpenApi(z);
88
+ extended = true;
89
+ }
90
+ const paths = {};
91
+ for (const descriptor of routes) {
92
+ const { method, path, config: routeConfig } = descriptor;
93
+ if (!method || path === "/**") continue;
94
+ const openApiPath = toOpenApiPath(path);
95
+ if (!paths[openApiPath]) paths[openApiPath] = {};
96
+ const operation = { responses: {} };
97
+ const requestParams = {};
98
+ if (routeConfig.request?.params) {
99
+ if (!(routeConfig.request.params instanceof z.ZodObject)) throw new Error(`params schema for ${method} ${path} must be a z.object()`);
100
+ requestParams.path = routeConfig.request.params;
101
+ }
102
+ if (routeConfig.request?.query) {
103
+ if (!(routeConfig.request.query instanceof z.ZodObject)) throw new Error(`query schema for ${method} ${path} must be a z.object()`);
104
+ requestParams.query = routeConfig.request.query;
105
+ }
106
+ if (Object.keys(requestParams).length > 0) operation.requestParams = requestParams;
107
+ if (routeConfig.request?.body) operation.requestBody = { content: { "application/json": { schema: routeConfig.request.body } } };
108
+ if (routeConfig.response && Object.keys(routeConfig.response).length > 0) for (const [status, schema] of Object.entries(routeConfig.response)) {
109
+ const code = Number(status);
110
+ const entry = { description: STATUS_TEXT[code] ?? "Response" };
111
+ if (code !== 204) entry.content = { "application/json": { schema } };
112
+ operation.responses[status] = entry;
113
+ }
114
+ else operation.responses = { 200: { description: "OK" } };
115
+ paths[openApiPath][method.toLowerCase()] = operation;
116
+ }
117
+ const specPath = config.specPath ?? "/openapi.json";
118
+ const docsPath = config.docsPath ?? "/docs";
119
+ const document = createDocument({
120
+ openapi: "3.1.0",
121
+ info: config.info,
122
+ servers: config.servers,
123
+ tags: config.tags,
124
+ security: config.security,
125
+ components: config.securitySchemes ? { securitySchemes: config.securitySchemes } : void 0,
126
+ paths
127
+ });
128
+ return {
129
+ spec: (route) => route.get(specPath, { resolve: () => Response.json(document) }),
130
+ docs: (route) => route.get(docsPath, { resolve: () => new Response(scalarHtml(specPath), { headers: { "content-type": "text/html" } }) })
131
+ };
132
+ }
133
+ //#endregion
134
+ export { openapi };
package/package.json ADDED
@@ -0,0 +1,58 @@
1
+ {
2
+ "name": "@hectoday/openapi",
3
+ "version": "0.1.0",
4
+ "description": "OpenAPI 3.1 spec generation for @hectoday/http routes.",
5
+ "keywords": [
6
+ "api",
7
+ "documentation",
8
+ "hectoday",
9
+ "openapi",
10
+ "spec",
11
+ "swagger"
12
+ ],
13
+ "homepage": "https://github.com/hectoday/http#readme",
14
+ "bugs": {
15
+ "url": "https://github.com/hectoday/http/issues"
16
+ },
17
+ "license": "MIT",
18
+ "repository": {
19
+ "type": "git",
20
+ "url": "git+https://github.com/hectoday/http.git",
21
+ "directory": "packages/openapi"
22
+ },
23
+ "files": [
24
+ "dist"
25
+ ],
26
+ "type": "module",
27
+ "types": "./src/index.ts",
28
+ "exports": {
29
+ ".": {
30
+ "types": "./src/index.ts",
31
+ "development": "./src/index.ts",
32
+ "default": "./dist/index.mjs"
33
+ },
34
+ "./package.json": "./package.json"
35
+ },
36
+ "scripts": {
37
+ "build": "vp pack",
38
+ "dev": "vp pack --watch",
39
+ "test": "vp test",
40
+ "typecheck": "tsc --noEmit"
41
+ },
42
+ "dependencies": {
43
+ "zod-openapi": "^4.2.4"
44
+ },
45
+ "devDependencies": {
46
+ "@hectoday/http": "^0.2.0",
47
+ "@types/node": "^25.5.0",
48
+ "bumpp": "^11.0.1",
49
+ "typescript": "^5.9.3",
50
+ "vite-plus": "latest",
51
+ "vitest": "npm:@voidzero-dev/vite-plus-test@latest",
52
+ "zod": "^3.24.0"
53
+ },
54
+ "peerDependencies": {
55
+ "@hectoday/http": "^0.2.0",
56
+ "zod": "^3.24.0"
57
+ }
58
+ }