OpenAPI Documentation Generator

Build a TypeScript utility that generates and validates OpenAPI metadata and documentation structures.

Overview

Create a module that constructs well-typed OpenAPI metadata sections including API information, contact details, license information, server configurations, and external documentation references. The module should provide strongly-typed builders and validators for these metadata components.

Requirements

API Information Builder

Create a function buildApiInfo that constructs complete API information with the following parameters:

• title (required)
• description (required)
• version (required)
• contact (optional object with name, url, and email fields)
• license (optional object with name and url fields)

The function should return a properly typed info object with all metadata fields.

• Given title "My API", description "A sample API", and version "1.0.0", returns an info object with these values @test
• Given title "My API", description "A sample API", version "1.0.0", contact {name: "Support", email: "support@example.com"}, and license {name: "MIT"}, returns an info object with all fields populated @test

Server Configuration Builder

Create a function buildServerConfig that constructs server configurations with:

• url (required)
• description (optional)

The function should return a properly typed server object.

• Given url "https://api.example.com" and description "Production server", returns a server object with these values @test
• Given only url "https://api.example.com" without description, returns a server object with just the url @test

External Documentation Builder

Create a function buildExternalDocs that constructs external documentation references with:

• url (required)
• description (optional)

The function should return a properly typed external documentation object.

• Given url "https://docs.example.com" and description "Full API documentation", returns an external docs object @test

Tag Builder

Create a function buildTag that constructs operation tags with:

• name (required)
• description (optional)
• externalDocs (optional)

The function should return a properly typed tag object.

• Given name "users" and description "User management operations", returns a tag object with these values @test
• Given name "users", description "User management operations", and externalDocs with url "https://docs.example.com/users", returns a complete tag object @test

Implementation

@generates

API

import type { OpenAPIV3 } from 'openapi-types';

/**
 * Builds an OpenAPI info object with required metadata and optional contact/license.
 */
export function buildApiInfo(
  title: string,
  description: string,
  version: string,
  contact?: { name?: string; url?: string; email?: string },
  license?: { name: string; url?: string }
): OpenAPIV3.InfoObject;

/**
 * Builds a server configuration object.
 */
export function buildServerConfig(
  url: string,
  description?: string
): OpenAPIV3.ServerObject;

/**
 * Builds an external documentation object.
 */
export function buildExternalDocs(
  url: string,
  description?: string
): OpenAPIV3.ExternalDocumentationObject;

/**
 * Builds a tag object for categorizing operations.
 */
export function buildTag(
  name: string,
  description?: string,
  externalDocs?: OpenAPIV3.ExternalDocumentationObject
): OpenAPIV3.TagObject;

Dependencies { .dependencies }

openapi-types { .dependency }

Provides TypeScript type definitions for OpenAPI specifications.