@voltro/plugin-openapi 0.69.1 → 0.71.0

package/dist/index.d.ts

@@ -2,6 +2,15 @@ import { ProcedureDescriptor } from '@voltro/protocol';
 import { RestRouteDescriptor } from '@voltro/protocol/rest';
 import { VoltroPlugin } from '@voltro/protocol';
 
+/**
+ * A body derived from a wire JSON schema, deterministically — the same schema
+ * always derives the same body, so a generated collection's diff stays quiet.
+ * Not a substitute for an author's `publicApi.example`: it exists so an
+ * operation without one is not an empty body in Swagger UI and in every
+ * collection, and it is marked `x-voltro-example: derived` where it is used.
+ */
+export declare const deriveExample: (schema: JsonObject, defs: Record<string, unknown>, depth?: number) => unknown;
+
 /**
  * Build the full OpenAPI 3.1 document from a list of REST descriptors and,
  * optionally, the rpc procedure descriptors.
@@ -11,7 +20,12 @@ import { VoltroPlugin } from '@voltro/protocol';
  */
 export declare function generateOpenApiSpec(routes: ReadonlyArray<RestRouteDescriptor<any, any>>, info?: OpenApiInfo): OpenApiDocument;
 
-export declare function generateOpenApiSpec(routes: ReadonlyArray<RestRouteDescriptor<any, any>>, info: OpenApiInfo, sources: OpenApiSources): OpenApiDocument;
+export declare function generateOpenApiSpec(routes: ReadonlyArray<RestRouteDescriptor<any, any>>, info: OpenApiInfo, sources: OpenApiSources, options?: OpenApiGenerateOptions): OpenApiDocument;
+
+declare type JsonObject = Record<string, unknown>;
+
+/** Every version mounted, newest first (`v2` before `v1`). */
+export declare const mountedVersions: (routes: ReadonlyArray<RestRouteDescriptor<any, any>>) => ReadonlyArray<string>;
 
 /** A minimal OpenAPI 3.1 document — the shape `generateOpenApiSpec` returns.
  *  Deliberately narrow: it names the top-level keys a deployment reads (so the
@@ -24,18 +38,79 @@ export declare interface OpenApiDocument {
         readonly title: string;
         readonly version: string;
         readonly description?: string;
+        readonly contact?: OpenApiInfo['contact'];
+        readonly license?: OpenApiInfo['license'];
+        readonly termsOfService?: string;
+        readonly 'x-logo'?: OpenApiInfo['logo'];
     };
+    readonly servers?: ReadonlyArray<{
+        readonly url: string;
+        readonly description?: string;
+        readonly 'x-voltro-environment'?: string;
+    }>;
+    readonly externalDocs?: OpenApiExternalDocs;
+    readonly 'x-voltro-environment'?: string;
+    /** The digest of the projected surface — what a generated client was built
+     *  from, and what `voltro check --public-api --against` compares. */
+    readonly 'x-voltro-surface-digest'?: string;
     readonly paths: Record<string, Record<string, unknown>>;
+    /** Every tag group an operation uses, with its description when one was given. */
+    readonly tags?: ReadonlyArray<{
+        readonly name: string;
+        readonly description?: string;
+        readonly externalDocs?: OpenApiExternalDocs;
+    }>;
     readonly components: {
         readonly schemas: Record<string, unknown>;
         readonly securitySchemes?: Record<string, unknown>;
     };
 }
 
+export declare interface OpenApiExternalDocs {
+    readonly url: string;
+    readonly description?: string;
+}
+
+/** What the generator knows beyond the routes: a description per tag group
+ *  (`teams` → "Teams and membership"), for the document's `tags[]`. */
+export declare interface OpenApiGenerateOptions {
+    readonly tagDescriptions?: Readonly<Record<string, string>>;
+    /** A link per tag group — the handbook page of a domain — for `tags[].externalDocs`. */
+    readonly tagExternalDocs?: Readonly<Record<string, OpenApiExternalDocs>>;
+    /** The document's `externalDocs`. */
+    readonly externalDocs?: OpenApiExternalDocs;
+    /** The document's `servers` — the first entry is what a generated client
+     *  and a collection take as the default base URL. */
+    readonly servers?: ReadonlyArray<OpenApiServer>;
+    /** The environment THIS instance serves (`x-voltro-environment` on the
+     *  document): `dev`, `staging`, `production`, … */
+    readonly environment?: string;
+}
+
 export declare interface OpenApiInfo {
     readonly title?: string;
     readonly version?: string;
     readonly description?: string;
+    /** The API team a consumer writes to — `info.contact`. */
+    readonly contact?: {
+        readonly name?: string;
+        readonly url?: string;
+        readonly email?: string;
+    };
+    /** `info.license`. */
+    readonly license?: {
+        readonly name: string;
+        readonly url?: string;
+        readonly identifier?: string;
+    };
+    /** `info.termsOfService` — a URL. */
+    readonly termsOfService?: string;
+    /** `x-logo` — what ReDoc renders at the top of the page. */
+    readonly logo?: {
+        readonly url: string;
+        readonly altText?: string;
+        readonly backgroundColor?: string;
+    };
 }
 
 export declare const openapiPlugin: (options: OpenApiPluginOptions) => VoltroPlugin;
@@ -54,6 +129,30 @@ export declare interface OpenApiPluginOptions {
     readonly procedures?: ReadonlyArray<ProcedureDescriptor>;
     /** Spec metadata. */
     readonly info?: OpenApiInfo;
+    /** A description per tag group (`teams` → 'Teams and membership'), for the
+     *  document's `tags[]`. A group with no entry is listed by name. */
+    readonly tagDescriptions?: Readonly<Record<string, string>>;
+    /** A link per tag group — the handbook page of a domain — for
+     *  `tags[].externalDocs`. */
+    readonly tagExternalDocs?: Readonly<Record<string, OpenApiExternalDocs>>;
+    /** The document's `externalDocs`. */
+    readonly externalDocs?: OpenApiExternalDocs;
+    /**
+     * Where the API is reachable — the document's `servers`. The first entry is
+     * the default base URL of a generated client and of a collection, and every
+     * entry becomes one environment file there. Omitted: one entry from
+     * `VOLTRO_PUBLIC_API_ORIGIN` when that is set (the public origin of THIS
+     * api — `VOLTRO_API_ORIGIN` is the web app's server-side route to it, and
+     * `VOLTRO_PUBLIC_URL` the storage plugin's), tagged with `environment`.
+     */
+    readonly servers?: ReadonlyArray<OpenApiServer>;
+    /**
+     * The environment this instance serves — `dev`, `staging`, `production` —
+     * written as `x-voltro-environment` on the document and on the default
+     * server entry. Default `VOLTRO_ENVIRONMENT`, else `production` under
+     * `NODE_ENV=production` and `dev` otherwise.
+     */
+    readonly environment?: string;
     /** Path to serve the JSON spec. Default `/openapi.json`. */
     readonly specPath?: string;
     /** Path to serve the Swagger-UI page. Default `/docs`. `false` disables it. */
@@ -74,6 +173,28 @@ export declare interface OpenApiPluginOptions {
      * `procedures` only.
      */
     readonly includeAppRoutes?: boolean;
+    /**
+     * Document the app's OWN rpc procedures — every query, mutation, action and
+     * stream discovery found, minus `internal` ones — without listing them in
+     * `procedures`. Default `false`: the spec stays REST-only unless asked. The
+     * framework hands the plugin the discovered descriptors
+     * (`onProcedureSurface`) once discovery has run, on both boot paths; one
+     * also passed in `procedures` is documented once. Importing the descriptor
+     * modules into `app.config.ts` to fill `procedures` evaluates every one of
+     * them before discovery on every load of the config — this option is the
+     * way around that.
+     */
+    readonly includeAppProcedures?: boolean;
+}
+
+/** One `servers[]` entry: where the API is reachable, and for which
+ *  environment (`x-voltro-environment`), so a collection can write one
+ *  environment file per entry. */
+export declare interface OpenApiServer {
+    readonly url: string;
+    readonly description?: string;
+    /** `dev` | `staging` | `production` — free text; the entry's environment. */
+    readonly environment?: string;
 }
 
 /** Extra sources to fold into the spec beyond the REST `routes`. Today: the
@@ -85,6 +206,29 @@ export declare interface OpenApiSources {
     readonly procedures?: ReadonlyArray<ProcedureDescriptor>;
 }
 
-export declare const swaggerUiHtml: (specUrl: string, title?: string) => string;
+/** RFC 9457 Problem Details — the error body of every projection under a
+ *  `problem-details` profile. Published once; each typed error's response
+ *  references it and names its `type`. */
+export declare const PROBLEM_DETAILS_SCHEMA_NAME = "ProblemDetails";
+
+/** One entry of Swagger UI's "Select a definition" dropdown. */
+declare interface SwaggerUiDefinition {
+    readonly url: string;
+    readonly name: string;
+}
+
+export declare const swaggerUiHtml: (specUrl: string, title?: string, options?: SwaggerUiOptions) => string;
+
+declare interface SwaggerUiOptions {
+    /** Several definitions — one per API version — shown as a dropdown in the
+     *  topbar (`urls`), instead of the single `url`. */
+    readonly urls?: ReadonlyArray<SwaggerUiDefinition>;
+    /** The dropdown's preselected entry (`urls.primaryName`). */
+    readonly primaryName?: string;
+}
+
+/** The dropdown name of a version: the version, with the earliest `sunset`
+ *  among its routes when one is declared — `v1 — sunset 2027-03-01`. */
+export declare const versionLabel: (version: string, routes: ReadonlyArray<RestRouteDescriptor<any, any>>) => string;
 
 export { }