@kizunajs/openapi 2.0.0-beta.0

package/dist/index.d.cts

@@ -0,0 +1,306 @@
+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";
+
+//#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.
+ */
+type OpenApiVersion = '3.1.0';
+interface OpenApiInfo {
+  title: string;
+  version: string;
+  description?: string;
+}
+interface OpenApiServer {
+  url: string;
+  description?: string;
+}
+interface OpenApiParameter {
+  name: string;
+  in: 'path' | 'query' | 'header' | 'cookie';
+  required?: boolean;
+  description?: string;
+  schema: Record<string, unknown>;
+}
+interface OpenApiResponseObject {
+  description: string;
+  headers?: Record<string, {
+    description?: string;
+    required?: boolean;
+    schema: Record<string, unknown>;
+  }>;
+  content?: Record<string, {
+    schema: Record<string, unknown>;
+  }>;
+}
+interface OpenApiExternalDocs {
+  url: string;
+  description?: string;
+}
+interface OpenApiTag {
+  name: string;
+  description?: string;
+  externalDocs?: OpenApiExternalDocs;
+}
+interface OpenApiOperation {
+  operationId?: string;
+  summary?: string;
+  description?: string;
+  deprecated?: boolean;
+  tags?: string[];
+  security?: Array<Record<string, string[]>>;
+  /**
+   * The `custom` schemes guarding this operation. They emit no `security`
+   * requirement, so this marks the operation as protected, not public.
+   */
+  'x-kizuna-guarded'?: string[];
+  /**
+   * The roles the route accepts, from the route's `auth.roles`.
+   */
+  'x-kizuna-roles'?: string[];
+  /**
+   * The permissions the caller has to hold, from the route's `auth.requires`.
+   */
+  'x-kizuna-requires'?: Record<string, string[]>;
+  externalDocs?: OpenApiExternalDocs;
+  parameters?: OpenApiParameter[];
+  requestBody?: {
+    required?: boolean;
+    content: Record<string, {
+      schema: Record<string, unknown>;
+    }>;
+  };
+  responses: Record<string, OpenApiResponseObject>;
+}
+interface OpenApiDocument {
+  openapi: string;
+  info: OpenApiInfo;
+  servers?: OpenApiServer[];
+  paths: Record<string, Record<string, OpenApiOperation>>;
+  tags?: OpenApiTag[];
+  externalDocs?: OpenApiExternalDocs;
+  components?: {
+    securitySchemes?: Record<string, unknown>;
+    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;
+}
+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;
+  /**
+   * Where the document is served. The UI embeds it, so this is only for
+   * publishing the file.
+   */
+  jsonPath?: JsonDocumentPath;
+  /**
+   * Where the document is served as YAML.
+   */
+  yamlPath?: YamlDocumentPath;
+  /**
+   * 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`
+   */
+  pageTitle?: string;
+  /**
+   * Merged into `Scalar.createApiReference` or `SwaggerUIBundle`.
+   */
+  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.
+ *
+ * @example
+ * ```ts
+ * export default defineConfig({
+ *     routes,
+ *     plugins: [
+ *         openApiPlugin({
+ *             info: {
+ *                 title: 'My API',
+ *                 version: '1.0.0',
+ *             },
+ *         }),
+ *     ],
+ * });
+ * ```
+ */
+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>;
+//#endregion
+//#region src/generator.d.ts
+/**
+ * Render from options held directly, for the plugin's own routes.
+ */
+declare function renderOpenApi(api: ApiDefinition, options: GenerateOpenApiOptions): OpenApiRenderer;
+/**
+ * Generate an OpenAPI 3.1.0 document from an api. Returns a renderer: call
+ * it with `'json'` or `'yaml'`. Options come from the `openApiPlugin` installed
+ * on the api, so the document matches the one the server serves.
+ *
+ * Pass `overrides` for what only a build step knows, such as the public
+ * `servers` list.
+ */
+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 };

package/dist/index.d.mts

@@ -0,0 +1,306 @@
+import { z } from "zod";
+import { RoutePath, WithSlug } from "kizunajs/plugin";
+import { RouteDefinition } from "kizunajs/generator";
+import * as _$kizunajs from "kizunajs";
+import { ApiDefinition, ClientTarget } from "kizunajs";
+
+//#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.
+ */
+type OpenApiVersion = '3.1.0';
+interface OpenApiInfo {
+  title: string;
+  version: string;
+  description?: string;
+}
+interface OpenApiServer {
+  url: string;
+  description?: string;
+}
+interface OpenApiParameter {
+  name: string;
+  in: 'path' | 'query' | 'header' | 'cookie';
+  required?: boolean;
+  description?: string;
+  schema: Record<string, unknown>;
+}
+interface OpenApiResponseObject {
+  description: string;
+  headers?: Record<string, {
+    description?: string;
+    required?: boolean;
+    schema: Record<string, unknown>;
+  }>;
+  content?: Record<string, {
+    schema: Record<string, unknown>;
+  }>;
+}
+interface OpenApiExternalDocs {
+  url: string;
+  description?: string;
+}
+interface OpenApiTag {
+  name: string;
+  description?: string;
+  externalDocs?: OpenApiExternalDocs;
+}
+interface OpenApiOperation {
+  operationId?: string;
+  summary?: string;
+  description?: string;
+  deprecated?: boolean;
+  tags?: string[];
+  security?: Array<Record<string, string[]>>;
+  /**
+   * The `custom` schemes guarding this operation. They emit no `security`
+   * requirement, so this marks the operation as protected, not public.
+   */
+  'x-kizuna-guarded'?: string[];
+  /**
+   * The roles the route accepts, from the route's `auth.roles`.
+   */
+  'x-kizuna-roles'?: string[];
+  /**
+   * The permissions the caller has to hold, from the route's `auth.requires`.
+   */
+  'x-kizuna-requires'?: Record<string, string[]>;
+  externalDocs?: OpenApiExternalDocs;
+  parameters?: OpenApiParameter[];
+  requestBody?: {
+    required?: boolean;
+    content: Record<string, {
+      schema: Record<string, unknown>;
+    }>;
+  };
+  responses: Record<string, OpenApiResponseObject>;
+}
+interface OpenApiDocument {
+  openapi: string;
+  info: OpenApiInfo;
+  servers?: OpenApiServer[];
+  paths: Record<string, Record<string, OpenApiOperation>>;
+  tags?: OpenApiTag[];
+  externalDocs?: OpenApiExternalDocs;
+  components?: {
+    securitySchemes?: Record<string, unknown>;
+    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;
+}
+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;
+  /**
+   * Where the document is served. The UI embeds it, so this is only for
+   * publishing the file.
+   */
+  jsonPath?: JsonDocumentPath;
+  /**
+   * Where the document is served as YAML.
+   */
+  yamlPath?: YamlDocumentPath;
+  /**
+   * 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`
+   */
+  pageTitle?: string;
+  /**
+   * Merged into `Scalar.createApiReference` or `SwaggerUIBundle`.
+   */
+  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.
+ *
+ * @example
+ * ```ts
+ * export default defineConfig({
+ *     routes,
+ *     plugins: [
+ *         openApiPlugin({
+ *             info: {
+ *                 title: 'My API',
+ *                 version: '1.0.0',
+ *             },
+ *         }),
+ *     ],
+ * });
+ * ```
+ */
+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>;
+//#endregion
+//#region src/generator.d.ts
+/**
+ * Render from options held directly, for the plugin's own routes.
+ */
+declare function renderOpenApi(api: ApiDefinition, options: GenerateOpenApiOptions): OpenApiRenderer;
+/**
+ * Generate an OpenAPI 3.1.0 document from an api. Returns a renderer: call
+ * it with `'json'` or `'yaml'`. Options come from the `openApiPlugin` installed
+ * on the api, so the document matches the one the server serves.
+ *
+ * Pass `overrides` for what only a build step knows, such as the public
+ * `servers` list.
+ */
+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 };