@kizunajs/openapi 2.0.0-beta.1 → 2.0.0-beta.11

package/dist/index.d.cts

@@ -1,67 +1,9 @@
-import * as _$kizunajs from "kizunajs";
-import { ApiDefinition, ClientTarget } from "kizunajs";
 import { z } from "zod";
-import { RoutePath, WithSlug } from "kizunajs/plugin";
 import { RouteDefinition } from "kizunajs/generator";
+import * as _$kizunajs from "kizunajs";
+import { ApiDefinition } from "kizunajs";
+import { RoutePath } from "kizunajs/plugin";
 
-//#region src/docs-html.d.ts
-/**
- * The API reference UI rendered by the docs endpoint.
- */
-type DocsProvider = 'scalar' | 'swagger';
-interface DocsHtmlOptions {
-  /**
-   * URL the UI fetches the OpenAPI document from. Omit it and pass
-   * {@link DocsHtmlOptions.specContent} instead.
-   */
-  specUrl?: string;
-  /**
-   * The document itself, embedded in the page rather than fetched.
-   */
-  specContent?: unknown;
-  /**
-   * Which API reference UI to render.
-   *
-   * @default 'scalar'
-   */
-  provider?: DocsProvider;
-  /**
-   * The page's `<title>`.
-   *
-   * @default 'API Reference'
-   */
-  pageTitle?: string;
-  /**
-   * Where to load the UI's assets from. Point this at a self-hosted copy for
-   * air-gapped deployments or a strict CSP.
-   *
-   * For `'scalar'` this is the script URL. For `'swagger'` it is the
-   * directory holding `swagger-ui.css` and `swagger-ui-bundle.js`.
-   *
-   * @default 'https://cdn.jsdelivr.net/npm/@scalar/api-reference@1' | 'https://cdn.jsdelivr.net/npm/swagger-ui-dist@5'
-   */
-  cdnUrl?: string;
-  /**
-   * Merged into `Scalar.createApiReference` or `SwaggerUIBundle`. See the
-   * provider's own documentation for the available keys.
-   */
-  configuration?: Record<string, unknown>;
-}
-/**
- * Render a self-contained page that loads an API reference UI over your OpenAPI
- * document. `openApiPlugin` calls this, so reach for it directly only when
- * kizuna has no adapter for your framework.
- *
- * @example
- * ```ts
- * const html = renderDocsHtml({
- *     specUrl: '/openapi.json',
- *     pageTitle: 'My API',
- * });
- * ```
- */
-declare const renderDocsHtml: (options: DocsHtmlOptions) => string;
-//#endregion
 //#region src/types.d.ts
 /**
  * The OpenAPI Specification version declared in the document's `openapi` field.
@@ -145,126 +87,214 @@ interface OpenApiDocument {
     schemas?: Record<string, unknown>;
   };
 }
-interface GenerateOpenApiOptions {
-  /**
-   * The OpenAPI Specification version to declare in the document's `openapi` field.
-   *
-   * Defaults to `'3.1.0'`.
-   */
-  openApiVersion?: OpenApiVersion;
-  info: OpenApiInfo;
-  servers?: OpenApiServer[];
-  externalDocs?: OpenApiExternalDocs;
-  setOperationId?: boolean | 'concatenated-path';
-  operationMapper?: (operation: OpenApiOperation, route: RouteDefinition, operationId: string) => OpenApiOperation;
-  /**
-   * Document the derived `head` operation on every `GET` path without a declared one.
-   *
-   * @default false
-   */
-  derivedHead?: boolean;
-}
+declare const GenerateOpenApiOptionsSchema: z.ZodObject<{
+  openApiVersion: z.ZodOptional<z.ZodLiteral<"3.1.0">>;
+  info: z.ZodObject<{
+    title: z.ZodString;
+    version: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>;
+  servers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    url: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>>;
+  externalDocs: z.ZodOptional<z.ZodObject<{
+    url: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+  setOperationId: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"concatenated-path">]>>;
+  includeHidden: z.ZodOptional<z.ZodBoolean>;
+  operationMapper: z.ZodOptional<z.ZodCustom<(operation: OpenApiOperation, route: RouteDefinition, operationId: string) => OpenApiOperation, (operation: OpenApiOperation, route: RouteDefinition, operationId: string) => OpenApiOperation>>;
+  derivedHead: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type GenerateOpenApiOptions = z.output<typeof GenerateOpenApiOptionsSchema>;
 interface OpenApiRenderer {
   (format: 'json'): OpenApiDocument;
   (format: 'yaml'): string;
 }
 //#endregion
 //#region src/plugin.d.ts
-declare const OPENAPI_PLUGIN_SLUG = "openApi";
 type JsonDocumentPath = `${RoutePath}.json`;
 type YamlDocumentPath = `${RoutePath}.yaml`;
-interface OpenApiPluginProps<Slug extends string = typeof OPENAPI_PLUGIN_SLUG> extends GenerateOpenApiOptions {
-  /**
-   * What handlers reach this plugin under. Give a second document its own.
-   *
-   * @default 'openApi'
-   */
-  slug?: Slug;
-  /**
-   * Where the reference UI is served.
-   */
-  docsPath?: RoutePath;
+declare const OpenApiPluginOptionsSchema: z.ZodObject<{
+  openApiVersion: z.ZodOptional<z.ZodLiteral<"3.1.0">>;
+  info: z.ZodObject<{
+    title: z.ZodString;
+    version: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>;
+  servers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    url: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>>;
+  externalDocs: z.ZodOptional<z.ZodObject<{
+    url: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+  setOperationId: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"concatenated-path">]>>;
+  includeHidden: z.ZodOptional<z.ZodBoolean>;
+  operationMapper: z.ZodOptional<z.ZodCustom<(operation: OpenApiOperation, route: _$kizunajs.RouteDefinition, operationId: string) => OpenApiOperation, (operation: OpenApiOperation, route: _$kizunajs.RouteDefinition, operationId: string) => OpenApiOperation>>;
+  derivedHead: z.ZodOptional<z.ZodBoolean>;
+  output: z.ZodOptional<z.ZodString>;
+  docsPath: z.ZodOptional<z.ZodCustom<`/${string}`, `/${string}`>>;
+  jsonPath: z.ZodOptional<z.ZodCustom<`/${string}.json`, `/${string}.json`>>;
+  yamlPath: z.ZodOptional<z.ZodCustom<`/${string}.yaml`, `/${string}.yaml`>>;
+  provider: z.ZodOptional<z.ZodEnum<{
+    scalar: "scalar";
+    swagger: "swagger";
+  }>>;
+  cdnUrl: z.ZodOptional<z.ZodString>;
+  pageTitle: z.ZodOptional<z.ZodString>;
+  configuration: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+type OpenApiPluginProps = z.output<typeof OpenApiPluginOptionsSchema>;
+/**
+ * Serve an API reference UI for the OpenAPI document, and the document itself
+ * if you publish it.
+ *
+ * The routes are public. Gate them with your framework's own middleware if that
+ * is not what you want.
+ *
+ * @example
+ * ```ts
+ * export default defineConfig({
+ *     routes,
+ *     plugins: [
+ *         openApiPlugin({
+ *             info: {
+ *                 title: 'My API',
+ *                 version: '1.0.0',
+ *             },
+ *             docsPath: '/docs',
+ *         }),
+ *     ],
+ * });
+ * ```
+ */
+declare const openApiPlugin: {
+  <const Slug extends string>(options: {
+    info: {
+      title: string;
+      version: string;
+      description?: string | undefined;
+    };
+    openApiVersion?: "3.1.0" | undefined;
+    servers?: {
+      url: string;
+      description?: string | undefined;
+    }[] | undefined;
+    externalDocs?: {
+      url: string;
+      description?: string | undefined;
+    } | undefined;
+    setOperationId?: boolean | "concatenated-path" | undefined;
+    includeHidden?: boolean | undefined;
+    operationMapper?: ((operation: OpenApiOperation, route: _$kizunajs.RouteDefinition, operationId: string) => OpenApiOperation) | undefined;
+    derivedHead?: boolean | undefined;
+    output?: string | undefined;
+    docsPath?: `/${string}` | undefined;
+    jsonPath?: `/${string}.json` | undefined;
+    yamlPath?: `/${string}.yaml` | undefined;
+    provider?: "scalar" | "swagger" | undefined;
+    cdnUrl?: string | undefined;
+    pageTitle?: string | undefined;
+    configuration?: Record<string, unknown> | undefined;
+  } & {
+    slug: Slug;
+  }): _$kizunajs.PluginDeclaration<Slug, {
+    routes: _$kizunajs.PluginRoutes;
+    generators: _$kizunajs.GeneratedFile[];
+  }>;
+  (options: {
+    info: {
+      title: string;
+      version: string;
+      description?: string | undefined;
+    };
+    openApiVersion?: "3.1.0" | undefined;
+    servers?: {
+      url: string;
+      description?: string | undefined;
+    }[] | undefined;
+    externalDocs?: {
+      url: string;
+      description?: string | undefined;
+    } | undefined;
+    setOperationId?: boolean | "concatenated-path" | undefined;
+    includeHidden?: boolean | undefined;
+    operationMapper?: ((operation: OpenApiOperation, route: _$kizunajs.RouteDefinition, operationId: string) => OpenApiOperation) | undefined;
+    derivedHead?: boolean | undefined;
+    output?: string | undefined;
+    docsPath?: `/${string}` | undefined;
+    jsonPath?: `/${string}.json` | undefined;
+    yamlPath?: `/${string}.yaml` | undefined;
+    provider?: "scalar" | "swagger" | undefined;
+    cdnUrl?: string | undefined;
+    pageTitle?: string | undefined;
+    configuration?: Record<string, unknown> | undefined;
+  }): _$kizunajs.PluginDeclaration<"openApi", {
+    routes: _$kizunajs.PluginRoutes;
+    generators: _$kizunajs.GeneratedFile[];
+  }>;
+};
+//#endregion
+//#region src/docs-html.d.ts
+/**
+ * The API reference UI rendered by the docs endpoint.
+ */
+type DocsProvider = 'scalar' | 'swagger';
+interface DocsHtmlOptions {
   /**
-   * Where the document is served. The UI embeds it, so this is only for
-   * publishing the file.
+   * URL the UI fetches the OpenAPI document from. Omit it and pass
+   * {@link DocsHtmlOptions.specContent} instead.
    */
-  jsonPath?: JsonDocumentPath;
+  specUrl?: string;
   /**
-   * Where the document is served as YAML.
+   * The document itself, embedded in the page rather than fetched.
    */
-  yamlPath?: YamlDocumentPath;
+  specContent?: unknown;
   /**
    * Which API reference UI to render.
    *
    * @default 'scalar'
    */
   provider?: DocsProvider;
-  /**
-   * Where to load the UI's assets from, for a self-hosted copy. The script
-   * URL for `'scalar'`; the directory holding `swagger-ui.css` and
-   * `swagger-ui-bundle.js` for `'swagger'`.
-   */
-  cdnUrl?: string;
   /**
    * The page's `<title>`.
    *
-   * @default the document's `info.title`
+   * @default 'API Reference'
    */
   pageTitle?: string;
   /**
-   * Merged into `Scalar.createApiReference` or `SwaggerUIBundle`.
+   * Where to load the UI's assets from. Point this at a self-hosted copy for
+   * air-gapped deployments or a strict CSP.
+   *
+   * For `'scalar'` this is the script URL. For `'swagger'` it is the
+   * directory holding `swagger-ui.css` and `swagger-ui-bundle.js`.
+   *
+   * @default 'https://cdn.jsdelivr.net/npm/@scalar/api-reference@1' | 'https://cdn.jsdelivr.net/npm/swagger-ui-dist@5'
+   */
+  cdnUrl?: string;
+  /**
+   * Merged into `Scalar.createApiReference` or `SwaggerUIBundle`. See the
+   * provider's own documentation for the available keys.
    */
   configuration?: Record<string, unknown>;
 }
 /**
- * Serve an API reference UI for the OpenAPI document, and the document itself
- * if you publish it.
- *
- * The routes are public. Gate them with your framework's own middleware if that
- * is not what you want.
+ * Render a self-contained page that loads an API reference UI over your OpenAPI
+ * document. `openApiPlugin` calls this, so reach for it directly only when
+ * kizuna has no adapter for your framework.
  *
  * @example
  * ```ts
- * export default defineConfig({
- *     routes,
- *     plugins: [
- *         openApiPlugin({
- *             info: {
- *                 title: 'My API',
- *                 version: '1.0.0',
- *             },
- *         }),
- *     ],
+ * const html = renderDocsHtml({
+ *     specUrl: '/openapi.json',
+ *     pageTitle: 'My API',
  * });
  * ```
  */
-declare const declare: (slug: string, props: OpenApiPluginProps<string>) => _$kizunajs.PluginDeclaration<{
-  readonly yaml?: {
-    readonly method: "GET";
-    readonly path: `/${string}.yaml`;
-    readonly summary: "OpenAPI document, as YAML";
-    readonly responses: {
-      readonly 200: z.ZodString;
-    };
-  } | undefined;
-  readonly json?: {
-    readonly method: "GET";
-    readonly path: `/${string}.json`;
-    readonly summary: "OpenAPI document";
-    readonly responses: {
-      readonly 200: z.ZodUnknown;
-    };
-  } | undefined;
-  readonly page?: {
-    readonly method: "GET";
-    readonly path: `/${string}`;
-    readonly summary: "API reference";
-    readonly responses: {
-      readonly 200: z.ZodString;
-    };
-  } | undefined;
-}, OpenApiPluginProps<string>, undefined, string, unknown>;
-declare function openApiPlugin<const Slug extends string = typeof OPENAPI_PLUGIN_SLUG>(props: OpenApiPluginProps<Slug>): WithSlug<ReturnType<typeof declare>, Slug>;
+declare const renderDocsHtml: (options: DocsHtmlOptions) => string;
 //#endregion
 //#region src/generator.d.ts
 /**
@@ -281,26 +311,4 @@ declare function renderOpenApi(api: ApiDefinition, options: GenerateOpenApiOptio
  */
 declare function generateOpenApi(api: ApiDefinition, overrides?: Partial<GenerateOpenApiOptions>): OpenApiRenderer;
 //#endregion
-//#region src/document-target.d.ts
-/**
- * Where the generated OpenAPI document is written. The format follows the
- * output extension: `.json` renders JSON, anything else renders YAML.
- */
-interface OpenApiDocumentOptions extends Partial<GenerateOpenApiOptions> {
-  /**
-   * Path the generated document is written to.
-   */
-  output: string;
-}
-/**
- * An OpenAPI document target for `kizuna.config.ts`.
- *
- * @example
- * openApiDocument({ output: './openapi.yaml' });
- */
-declare const openApiDocument: ({
-  output,
-  ...overrides
-}: OpenApiDocumentOptions) => ClientTarget;
-//#endregion
-export { type DocsHtmlOptions, type DocsProvider, type GenerateOpenApiOptions, type JsonDocumentPath, type OpenApiDocument, type OpenApiDocumentOptions, type OpenApiInfo, type OpenApiOperation, type OpenApiParameter, type OpenApiPluginProps, type OpenApiRenderer, type OpenApiResponseObject, type OpenApiServer, type OpenApiTag, type OpenApiVersion, type YamlDocumentPath, generateOpenApi, openApiDocument, openApiPlugin, renderDocsHtml, renderOpenApi };
+export { type DocsHtmlOptions, type DocsProvider, type GenerateOpenApiOptions, type JsonDocumentPath, type OpenApiDocument, type OpenApiInfo, type OpenApiOperation, type OpenApiParameter, type OpenApiPluginProps, type OpenApiRenderer, type OpenApiResponseObject, type OpenApiServer, type OpenApiTag, type OpenApiVersion, type YamlDocumentPath, generateOpenApi, openApiPlugin, renderDocsHtml, renderOpenApi };