@voltro/plugin-openapi 0.70.0 → 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.
@@ -13,6 +22,8 @@ export declare function generateOpenApiSpec(routes: ReadonlyArray<RestRouteDescr
 
 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>;
 
@@ -27,12 +38,27 @@ 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>;
@@ -40,16 +66,51 @@ export declare interface OpenApiDocument {
     };
 }
 
+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;
@@ -71,6 +132,27 @@ export declare interface OpenApiPluginOptions {
     /** 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. */
@@ -105,6 +187,16 @@ export declare interface OpenApiPluginOptions {
     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
  *  rpc procedure descriptors (queries / mutations / actions / streams). */
 export declare interface OpenApiSources {