hono-openapi 0.4.8 → 0.5.0-rc.0

package/README.md

@@ -1,270 +1,21 @@
 # 📜 Hono OpenAPI
 
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/rhinobase/hono-openapi)
 [![npm version](https://img.shields.io/npm/v/hono-openapi.svg)](https://npmjs.org/package/hono-openapi "View this project on NPM")
 [![npm downloads](https://img.shields.io/npm/dm/hono-openapi)](https://www.npmjs.com/package/hono-openapi)
-[![license](https://img.shields.io/npm/l/hono-openapi)](LICENSE)
 
 This can automatically generate the OpenAPI specification for the Hono API using your validation schema, which can be used to generate client libraries, documentation, and more.
 
-Supported Validation Libraries:
+This lib supports all the validation libs which are [Standard Schema](https://standardschema.dev/) compliant.
 
-- [x] [Zod](https://zod.dev/)
-- [x] [Valibot](https://valibot.dev/)
-- [x] [ArkType](https://arktype.io/)
-- [x] [TypeBox](https://github.com/sinclairzx81/typebox)
-- [x] [Effect](https://effect.website/docs/schema/introduction/)
+For documentation visit [honohub.dev](https://honohub.dev).
 
 > [!Note]
 > This package is still in development and your feedback is highly appreciated. If you have any suggestions or issues, please let us know by creating an issue on GitHub.
 
-## Usage
-
-### Installation
-
-You can install the package using favorite package manager.
-
-#### For Zod
-
-```bash
-pnpm add hono-openapi @hono/zod-validator zod zod-openapi
-```
-
-#### For Valibot
-
-```bash
-pnpm add hono-openapi @hono/valibot-validator valibot @valibot/to-json-schema
-```
-
-#### For ArkType
-
-```bash
-pnpm add hono-openapi @hono/arktype-validator arktype
-```
-
-#### For TypeBox
-
-```bash
-pnpm add hono-openapi @hono/typebox-validator @sinclair/typebox
-```
-
-#### For Effect
-
-```bash
-pnpm add hono-openapi @hono/effect-validator effect
-```
-
-> [!IMPORTANT]
->
-> Requires `effect@^3.10.0`.
-> Also, use the `Schema` class from the `effect` package, as `@effect/schema` is not supported.
-
-### Basic Usage
-
-#### Setting up your application
-
-First, define your schemas, here is an example using Zod:
-
-```ts
-import z from "zod";
-
-// For extending the Zod schema with OpenAPI properties
-import "zod-openapi/extend";
-
-const querySchema = z
-  .object({
-    name: z.string().optional().openapi({ example: "Steven" }),
-  })
-  .openapi({ ref: "Query" });
-
-const responseSchema = z.string().openapi({ example: "Hello Steven!" });
-```
-
-Extending the Zod schema with OpenAPI properties is optional, but it will help you generate the OpenAPI specification. You can learn more about it here - [https://github.com/samchungy/zod-openapi](https://github.com/samchungy/zod-openapi).
-
-> [!Tip]
-> The `querySchema` schema will be registered as "#/components/schemas/Query" refs in the OpenAPI document. If you want to register the schema as referenced components, use .openapi() method.
-
-Next, create your route -
-
-```ts
-import { Hono } from "hono";
-import { describeRoute } from "hono-openapi";
-import { resolver, validator as zValidator } from "hono-openapi/zod";
-
-const app = new Hono();
-
-app.get(
-  "/",
-  describeRoute({
-    description: "Say hello to the user",
-    responses: {
-      200: {
-        description: "Successful greeting response",
-        content: {
-          "text/plain": {
-            schema: resolver(responseSchema),
-          },
-        },
-      },
-    },
-  }),
-  zValidator("query", querySchema),
-  (c) => {
-    const query = c.req.valid("query");
-    return c.text(`Hello ${query?.name ?? "Hono"}!`);
-  }
-);
-```
-
-You might be wondering why are we importing `validator` from `hono-openapi/zod` instead of `@hono/zod-validator` and as `zValidator`? This is because `hono-openapi` provides a wrapper around the `@hono/zod-validator` to make it easier to use. The idea is if you are already using `@hono/zod-validator` to validate your schemas, you can easily switch to `hono-openapi` without changing much of your code.
-
-Finally, generate the OpenAPI specification -
-
-```ts
-app.get(
-  "/openapi",
-  openAPISpecs(app, {
-    documentation: {
-      info: {
-        title: "Hono",
-        version: "1.0.0",
-        description: "API for greeting users",
-      },
-      servers: [
-        {
-          url: "http://localhost:3000",
-          description: "Local server",
-        },
-      ],
-    },
-  })
-);
-```
-
-Now, you can access the OpenAPI specification by visiting `http://localhost:3000/openapi`, and you can use this specification to generate client libraries, documentation, and more. Some tools that I used to generate documentation are -
-
-- [Swagger UI](https://github.com/honojs/middleware/tree/main/packages/swagger-ui)
-- [Scalar](https://www.npmjs.com/package/@scalar/hono-api-reference)
-
-##### Scalar Example
-
-```ts
-app.get(
-  "/docs",
-  Scalar({
-    theme: "saturn",
-    url: "/openapi",
-  })
-);
-```
-
-And that's it! You have successfully generated the OpenAPI specification for your Hono API.
-
-### Advanced Usage
-
-#### Adding Security Definitions
-
-You can add security definitions to your OpenAPI specification by using the `security` property in the `openAPISpecs` function.
-
-```ts
-app.get(
-  "/openapi",
-  openAPISpecs(appRouter, {
-    documentation: {
-      info: {
-        title: "Rhinobase Cloud",
-        version: "1.0.0",
-        description: "API Documentation",
-      },
-      components: {
-        securitySchemes: {
-          bearerAuth: {
-            type: "http",
-            scheme: "bearer",
-            bearerFormat: "JWT",
-          },
-        },
-      },
-      security: [
-        {
-          bearerAuth: [],
-        },
-      ],
-      servers: [
-        {
-          url: "http://localhost:3004",
-          description: "Local server",
-        },
-      ],
-    },
-  })
-);
-```
-
-#### Conditionaly Hiding Routes
-
-You can conditionally hide routes from the OpenAPI specification by using the `hide` property in the `describeRoute` function.
-
-```ts
-app.get(
-  "/",
-  describeRoute({
-    // ...
-    hide: process.env.NODE_ENV === "production",
-  }),
-  (c) => {
-    return c.text("Private Route");
-  }
-);
-```
-
-#### Validating Responses
-
-> [!Warning]
-> Experimental
-
-You can validate the responses using the `validateResponse` property in the `describeRoute` function. This will validate the response against the schema and return an error if the response is invalid.
-
-```ts
-app.get(
-  "/",
-  describeRoute({
-    // ...
-    validateResponse: true,
-  }),
-  (c) => {
-    return c.json({ message: "This response will be validated" });
-  }
-);
-```
-
-#### Persisting OpenAPI Spec to a file
-
-You can save the spec to a file for cache or any other external use.
-
-```ts
-import fs from 'node:fs';
-import { openAPISpecs, generateSpecs } from 'hono-openapi';
-
-const options = {/* ... */};
-const app = new Hono()
-  .get(
-    "/openapi",
-    openAPISpecs(app, options),
-  );
-
-generateSpecs(app, options)
-  .then(spec => {
-    const pathToSpec = "openapi.json"
-    fs.writeFileSync(pathToSpec, JSON.stringify(spec, null, 2));
-  })
-```
-
 ## Contributing
 
-We would love to have more contributors involved!
-
-To get started, please read our [Contributing Guide](https://github.com/rhinobase/hono-openapi/blob/main/CONTRIBUTING.md).
+Visit our [contributing docs](https://github.com/rhinobase/hono-openapi/blob/main/CONTRIBUTING.md).
 
 ## Credits
 

package/dist/index.cjs

@@ -0,0 +1,410 @@
+'use strict';
+
+var standardValidator = require('@hono/standard-validator');
+var standardJson = require('@standard-community/standard-json');
+var standardOpenapi = require('@standard-community/standard-openapi');
+
+const uniqueSymbol = Symbol("openapi");
+const ALLOWED_METHODS = [
+  "GET",
+  "PUT",
+  "POST",
+  "DELETE",
+  "OPTIONS",
+  "HEAD",
+  "PATCH",
+  "TRACE"
+];
+const toOpenAPIPath = (path) => path.split("/").map((x) => {
+  let tmp = x;
+  if (tmp.startsWith(":")) {
+    const match = tmp.match(/^:([^{?]+)(?:{(.+)})?(\?)?$/);
+    if (match) {
+      const paramName = match[1];
+      tmp = `{${paramName}}`;
+    } else {
+      tmp = tmp.slice(1, tmp.length);
+      if (tmp.endsWith("?")) tmp = tmp.slice(0, -1);
+      tmp = `{${tmp}}`;
+    }
+  }
+  return tmp;
+}).join("/");
+const capitalize = (word) => word.charAt(0).toUpperCase() + word.slice(1);
+const generateOperationIdCache = /* @__PURE__ */ new Map();
+const generateOperationId = (route) => {
+  const operationIdKey = `${route.method}:${route.path}`;
+  if (generateOperationIdCache.has(operationIdKey)) {
+    return generateOperationIdCache.get(operationIdKey);
+  }
+  let operationId = route.method;
+  if (route.path === "/") return `${operationId}Index`;
+  for (const segment of route.path.split("/")) {
+    if (segment.charCodeAt(0) === 123) {
+      operationId += `By${capitalize(segment.slice(1, -1))}`;
+    } else {
+      operationId += capitalize(segment);
+    }
+  }
+  generateOperationIdCache.set(operationIdKey, operationId);
+  return operationId;
+};
+const paramKey = (param) => "$ref" in param ? param.$ref : `${param.in} ${param.name}`;
+function mergeParameters(...params) {
+  const _params = params.flatMap((x) => x ?? []);
+  const merged = _params.reduce((acc, param) => {
+    acc.set(paramKey(param), param);
+    return acc;
+  }, /* @__PURE__ */ new Map());
+  return Array.from(merged.values());
+}
+function getProperty(obj, key, defaultValue) {
+  if (obj != null && key in obj) {
+    return obj[key];
+  }
+  return defaultValue;
+}
+const specsByPathContext = /* @__PURE__ */ new Map();
+function getPathContext(path) {
+  const keys = Array.from(specsByPathContext.keys());
+  const context = [];
+  for (const key of keys) {
+    if (path.match(key)) {
+      const data = specsByPathContext.get(key);
+      if (!data) continue;
+      context.push(data);
+    }
+  }
+  return context;
+}
+function mergeSpecs(...specs) {
+  return specs.reduce(
+    (prev, spec) => {
+      if (!spec) return prev;
+      return {
+        ...prev,
+        ...spec,
+        tags: Array.from(
+          /* @__PURE__ */ new Set([
+            ...getProperty(prev, "tags") ?? [],
+            ...getProperty(spec, "tags") ?? []
+          ])
+        ),
+        parameters: mergeParameters(
+          getProperty(prev, "parameters"),
+          getProperty(spec, "parameters")
+        ),
+        responses: {
+          ...getProperty(prev, "responses", {}),
+          ...getProperty(spec, "responses", {})
+        }
+      };
+    },
+    {}
+  );
+}
+function registerSchemaPath({
+  route,
+  specs,
+  paths
+}) {
+  const path = toOpenAPIPath(route.path);
+  const method = route.method.toLowerCase();
+  if (method === "all") {
+    if (!specs) return;
+    if (specsByPathContext.has(path)) {
+      const prev = specsByPathContext.get(path) ?? {};
+      specsByPathContext.set(path, mergeSpecs(prev, specs));
+    } else {
+      specsByPathContext.set(path, specs);
+    }
+  } else {
+    const pathContext = getPathContext(path);
+    paths[path] = {
+      ...paths[path] ? paths[path] : {},
+      [method]: {
+        operationId: generateOperationId(route),
+        ...mergeSpecs(...pathContext, paths[path]?.[method], specs)
+      }
+    };
+  }
+}
+function removeExcludedPaths(paths, ctx) {
+  const { exclude, excludeStaticFile } = ctx.options;
+  const newPaths = {};
+  const _exclude = Array.isArray(exclude) ? exclude : [exclude];
+  for (const [key, value] of Object.entries(paths)) {
+    const isPathExcluded = !_exclude.some((x) => {
+      if (typeof x === "string") return key === x;
+      return x.test(key);
+    });
+    const isStaticFileExcluded = excludeStaticFile ? !key.includes(".") || key.includes("{") : true;
+    if (isPathExcluded && !(key.includes("*") && !key.includes("{")) && isStaticFileExcluded && value != null) {
+      for (const method of Object.keys(value)) {
+        const schema = value[method];
+        if (key.includes("{")) {
+          if (!schema.parameters) schema.parameters = [];
+          const pathParameters = key.split("/").filter(
+            (x) => x.startsWith("{") && !schema.parameters.find(
+              (params) => params.in === "path" && params.name === x.slice(1, x.length - 1)
+            )
+          );
+          for (const param of pathParameters) {
+            const paramName = param.slice(1, param.length - 1);
+            const index = schema.parameters.findIndex(
+              (x) => x.in === "param" && x.name === paramName
+            );
+            if (index !== -1) schema.parameters[index].in = "path";
+            else {
+              schema.parameters.push({
+                schema: { type: "string" },
+                in: "path",
+                name: paramName,
+                required: true
+              });
+            }
+          }
+        }
+        if (!schema.responses) {
+          schema.responses = {
+            200: {}
+          };
+        }
+      }
+      newPaths[key] = value;
+    }
+  }
+  return newPaths;
+}
+
+const DEFAULT_OPTIONS = {
+  documentation: {},
+  excludeStaticFile: true,
+  exclude: [],
+  excludeMethods: ["OPTIONS"],
+  excludeTags: []
+};
+async function generateSpecs(hono, options = DEFAULT_OPTIONS, c) {
+  const ctx = {
+    components: {},
+    // @ts-expect-error
+    options: {
+      ...DEFAULT_OPTIONS,
+      ...options
+    }
+  };
+  const _documentation = ctx.options.documentation ?? {};
+  const schema = await generatePaths(hono, ctx);
+  for (const path in schema) {
+    for (const method in schema[path]) {
+      const isHidden = getHiddenValue({
+        valueOrFunc: schema[path][method]?.hide,
+        method,
+        path,
+        c
+      });
+      if (isHidden) {
+        delete schema[path][method];
+      }
+    }
+  }
+  return {
+    openapi: "3.1.0",
+    ..._documentation,
+    tags: _documentation.tags?.filter(
+      (tag) => !ctx.options.excludeTags?.includes(tag?.name)
+    ),
+    info: {
+      title: "Hono Documentation",
+      description: "Development documentation",
+      version: "0.0.0",
+      ..._documentation.info
+    },
+    paths: {
+      ...removeExcludedPaths(schema, ctx),
+      ..._documentation.paths
+    },
+    components: {
+      ..._documentation.components,
+      schemas: {
+        ...ctx.components.schemas,
+        ..._documentation.components?.schemas
+      }
+    }
+  };
+}
+async function generatePaths(hono, ctx) {
+  const paths = {};
+  for (const route of hono.routes) {
+    if (!(uniqueSymbol in route.handler)) {
+      if (ctx.options.includeEmptyPaths) {
+        registerSchemaPath({
+          route,
+          paths
+        });
+      }
+      continue;
+    }
+    const routeMethod = route.method;
+    if (routeMethod !== "ALL") {
+      if (ctx.options.excludeMethods?.includes(routeMethod)) {
+        continue;
+      }
+      if (!ALLOWED_METHODS.includes(routeMethod)) {
+        continue;
+      }
+    }
+    const middlewareHandler = route.handler[uniqueSymbol];
+    const defaultOptionsForThisMethod = ctx.options.defaultOptions?.[routeMethod];
+    const { schema: routeSpecs, components = {} } = await getSpec(
+      middlewareHandler,
+      defaultOptionsForThisMethod
+    );
+    ctx.components = {
+      ...ctx.components,
+      ...components,
+      schemas: {
+        ...ctx.components.schemas,
+        ...components.schemas
+      }
+    };
+    registerSchemaPath({
+      route,
+      specs: routeSpecs,
+      paths
+    });
+  }
+  return paths;
+}
+function getHiddenValue(options) {
+  const { valueOrFunc, c, method, path } = options;
+  if (valueOrFunc != null) {
+    if (typeof valueOrFunc === "boolean") {
+      return valueOrFunc;
+    } else if (typeof valueOrFunc === "function") {
+      if (c) {
+        return valueOrFunc(c);
+      } else {
+        console.warn(
+          `'c' is not defined, cannot evaluate hide function for ${method} ${path}`
+        );
+      }
+    }
+  }
+  return false;
+}
+async function getSpec(middlewareHandler, defaultOptions) {
+  if ("spec" in middlewareHandler) {
+    let components = {};
+    const tmp = {
+      ...defaultOptions,
+      ...middlewareHandler.spec,
+      responses: {
+        ...defaultOptions?.responses,
+        ...middlewareHandler.spec.responses
+      }
+    };
+    if (tmp.responses) {
+      for (const key of Object.keys(tmp.responses)) {
+        const response = tmp.responses[key];
+        if (!response || !("content" in response)) continue;
+        for (const contentKey of Object.keys(response.content ?? {})) {
+          const raw = response.content?.[contentKey];
+          if (!raw) continue;
+          if (raw.schema && "toOpenAPISchema" in raw.schema) {
+            const result2 = await raw.schema.toOpenAPISchema(defaultOptions);
+            raw.schema = result2.schema;
+            if (result2.components) {
+              components = {
+                ...components,
+                ...result2.components
+              };
+            }
+          }
+        }
+      }
+    }
+    return { schema: tmp, components };
+  }
+  const result = await middlewareHandler.toOpenAPISchema();
+  const docs = {};
+  if (middlewareHandler.target === "form" || middlewareHandler.target === "json") {
+    const media = middlewareHandler.target === "json" ? "application/json" : "multipart/form-data";
+    if (!docs.requestBody || !("content" in docs.requestBody) || !docs.requestBody.content) {
+      docs.requestBody = {
+        content: {
+          [media]: {
+            schema: result.schema
+          }
+        }
+      };
+    } else {
+      docs.requestBody.content[media] = {
+        schema: result.schema
+      };
+    }
+  } else {
+    const parameters = [];
+    if ("$ref" in result.schema) {
+      parameters.push({
+        in: middlewareHandler.target,
+        // @ts-expect-error
+        name: result.schema.$ref,
+        // @ts-expect-error
+        schema: result.schema
+      });
+    } else {
+      for (const [key, value] of Object.entries(
+        result.schema.properties ?? {}
+      )) {
+        parameters.push({
+          in: middlewareHandler.target,
+          name: key,
+          // @ts-expect-error
+          schema: value,
+          required: result.schema.required?.includes(key)
+        });
+      }
+    }
+    docs.parameters = parameters;
+  }
+  return { schema: docs, components: result.components };
+}
+
+function resolver(schema) {
+  return {
+    vendor: schema["~standard"].vendor,
+    validate: schema["~standard"].validate,
+    toJSONSchema: (options) => standardJson.toJsonSchema(schema, options),
+    toOpenAPISchema: (options) => standardOpenapi.toOpenAPISchema(schema, options)
+  };
+}
+function validator(target, schema, hook, options) {
+  const middleware = standardValidator.sValidator(target, schema, hook);
+  return Object.assign(middleware, {
+    [uniqueSymbol]: {
+      target,
+      ...resolver(schema),
+      options
+    }
+  });
+}
+function describeRoute(spec) {
+  const middleware = async (_c, next) => {
+    await next();
+  };
+  return Object.assign(middleware, {
+    [uniqueSymbol]: {
+      spec
+    }
+  });
+}
+
+exports.ALLOWED_METHODS = ALLOWED_METHODS;
+exports.describeRoute = describeRoute;
+exports.generateSpecs = generateSpecs;
+exports.registerSchemaPath = registerSchemaPath;
+exports.removeExcludedPaths = removeExcludedPaths;
+exports.resolver = resolver;
+exports.uniqueSymbol = uniqueSymbol;
+exports.validator = validator;