@samveys/openapi

# breakingAllowed Function

Breaking changes are allowed only when the major version increased (or on 0.x, per SemVer §4).

function breakingAllowed(previous: string, next: string): boolean;

Exported from packages/openapi/src/diff.ts

# buildOpenApi Function

Builds an OpenAPI 3.1 document from the router's routes and their schemas. Bodies and responses come from the route's `body` and `response` schemas, parameters from `params` and `query`, and every operation lists the RFC 9457 problem responses the kernel can send.

function buildOpenApi(router: Router, options: OpenApiOptions): OpenApiDocument;

Exported from packages/openapi/src/document.ts

# diffOpenApi Function

Finds the changes from `base` to `head` and marks the ones that break existing clients. The rules follow the oasdiff "breaking" set for the parts Samveys documents: removed operations, response fields, enum values and types; new required request fields and parameters.

function diffOpenApi(base: OpenApiDocument, head: OpenApiDocument): readonly ApiChange[];

Exported from packages/openapi/src/diff.ts

# generateClient Function

Writes a typed fetch client for the document. Types are precomputed interfaces, so editors do not re-infer every route. Each operation becomes a method named by its operationId.

function generateClient(document: OpenApiDocument): string;

Exported from packages/openapi/src/client.ts

# majorOf Function

`1.4.2` → 1; anything that is not semver → NaN.

function majorOf(version: string): number;

Exported from packages/openapi/src/diff.ts

# openapi Function

The `@samveys/openapi` plugin: `/docs` in development and the `generate:*` / `openapi:diff` commands.

function openapi(options: OpenApiPluginOptions): import("@samveys/core").Plugin<OpenApiPluginOptions>;

Exported from packages/openapi/src/plugin.ts

# schemaToType Function

A TypeScript type for a JSON Schema, written out in full (no inference left for the editor).

function schemaToType(schema: unknown, indent?: string): string;

Exported from packages/openapi/src/client.ts

# toOpenApiPath Function

`/users/:id` → `/users/{id}`; an optional `:id?` and a wildcard `*name` become plain path params.

function toOpenApiPath(pattern: string): string;

Exported from packages/openapi/src/document.ts

# ApiChange Interface

One finding of `diffOpenApi`.

interface ApiChange {
    readonly breaking: boolean;
    /** Stable rule id, e.g. `response-property-removed`. */
    readonly rule: string;
    /** `GET /users/{id}` plus the JSON pointer of the change. */
    readonly where: string;
    readonly message: string;
}

Exported from packages/openapi/src/contracts.ts

# OpenApiDocument Interface

An OpenAPI 3.1 document; only the parts this package writes are typed.

interface OpenApiDocument {
    readonly openapi: '3.1.0';
    readonly info: {
        readonly title: string;
        readonly version: string;
        readonly description?: string;
    };
    readonly paths: Readonly<Record<string, Readonly<Record<string, OpenApiOperation>>>>;
    readonly components: {
        readonly schemas: Readonly<Record<string, unknown>>;
    };
}

Exported from packages/openapi/src/contracts.ts

# OpenApiOperation Interface

No documentation comment.

interface OpenApiOperation {
    readonly operationId: string;
    readonly deprecated?: boolean;
    readonly parameters?: readonly OpenApiParameter[];
    readonly requestBody?: {
        readonly required: boolean;
        readonly content: {
            readonly 'application/json': {
                readonly schema: unknown;
            };
  …

interface OpenApiOperation {
    readonly operationId: string;
    readonly deprecated?: boolean;
    readonly parameters?: readonly OpenApiParameter[];
    readonly requestBody?: {
        readonly required: boolean;
        readonly content: {
            readonly 'application/json': {
                readonly schema: unknown;
            };
        };
    };
    readonly responses: Readonly<Record<string, {
        readonly description: string;
        readonly content?: Readonly<Record<string, {
            readonly schema: unknown;
        }>>;
    }>>;
}

Exported from packages/openapi/src/contracts.ts

# OpenApiOptions Interface

No documentation comment.

interface OpenApiOptions {
    readonly title: string;
    /** API version (semver), used by `svs openapi:diff`. */
    readonly version: string;
    readonly description?: string;
}

Exported from packages/openapi/src/contracts.ts

# OpenApiParameter Interface

No documentation comment.

interface OpenApiParameter {
    readonly name: string;
    readonly in: 'path' | 'query';
    readonly required: boolean;
    readonly schema: unknown;
}

Exported from packages/openapi/src/contracts.ts

# OpenApiPluginOptions Interface

No documentation comment.

interface OpenApiPluginOptions extends OpenApiOptions {
    /** Default `/docs` (`/docs/openapi.json` for the JSON). */
    readonly path?: string;
    /** Serve `/docs` outside the `local` environment too. Default false. */
    readonly serveInProduction?: boolean;
}

Exported from packages/openapi/src/contracts.ts