Code Sample Generators

Overview

Code sample generators translate normalized API request data, headers, cookies, and payloads into executable client code snippets across multiple programming languages and scripting environments. By transforming parsed OpenAPI operation objects and media adapters into formatted target syntax, the generator suite powers interactive API documentation tabs and dynamic code preview widgets.

Sources: packages/openapi/src/requests/generators/all.ts:9-16, packages/openapi/src/ui/operation/usage-tabs.tsx:137-181

Code Generator Registry

Registry Interface and Types

The registry relies on types imported from @fumadocs/api-docs/codegen, instantiating them with specific type arguments for OpenAPI request payloads. CodeUsageGeneratorRegistry is defined as a registry mapping language identifiers to generator functions that accept RequestData & { url: string } and a context containing mediaAdapters (a record of string keys to MediaAdapter objects) and a custom configuration property.

Copyexport type CodeUsageGeneratorRegistry = Shared.CodeUsageGeneratorRegistry<
  RequestData & { url: string },
  { mediaAdapters: Record<string, MediaAdapter>; custom: unknown }
>;

Sources: packages/openapi/src/requests/generators/index.ts:35-38

CodeUsageGenerator and InlineCodeUsageGenerator represent single generator functions for specified programming languages, where the inline variant permits generic customization typing for the custom context field.

Copyexport type CodeUsageGenerator = Shared.CodeUsageGenerator<
  RequestData & { url: string },
  { mediaAdapters: Record<string, MediaAdapter>; custom: unknown }
>;
 
export type InlineCodeUsageGenerator<T = unknown> = Shared.InlineCodeUsageGenerator<
  RequestData & { url: string },
  { mediaAdapters: Record<string, MediaAdapter>; custom: T }
>;

Sources: packages/openapi/src/requests/generators/index.ts:43-54

createCodeUsageGeneratorRegistry wraps the shared factory function to produce new registry instances, optionally accepting an inherited registry parameter for scoping or fallback behaviors.

Copyexport function createCodeUsageGeneratorRegistry(
  inherit?: CodeUsageGeneratorRegistry,
): CodeUsageGeneratorRegistry {
  return Shared.createCodeUsageGeneratorRegistry(inherit);
}

Sources: packages/openapi/src/requests/generators/index.ts:56-60

Default Generator Registration

The registerDefault function populates a CodeUsageGeneratorRegistry instance by binding default language generator modules to specific string keys. It registers six built-in target generators before returning the modified registry instance.

Sources: packages/openapi/src/requests/generators/all.ts:2-16

Copyexport function registerDefault(registry: CodeUsageGeneratorRegistry) {
  registry.add('curl', curl);
  registry.add('js', javascript);
  registry.add('go', go);
  registry.add('python', python);
  registry.add('java', java);
  registry.add('csharp', csharp);
  return registry;
}

Sources: packages/openapi/src/requests/generators/all.ts:9-16

Request Data Extraction

Example Resolution and Parameter Locations

Extracting and preparing request information for code sample generation involves resolving parameters across operations and path items, picking schema examples, and sampling body contents. The process starts by gathering parameters from both operation.parameters and pathItem.parameters, and identifying the preferred request media type via getPreferredType. Sources: packages/openapi/src/utils/get-example-requests.ts:36-39

Copyexport function getPreferredType(body: Record<string, unknown>): string | undefined {
  if ('application/json' in body) return 'application/json';
 
  return Object.keys(body)[0];
}

Sources: packages/openapi/src/utils/schema.ts:8-12

When constructing example requests through getExampleRequests, the utility checks whether explicit body examples are defined under bodyOfType.examples. If present, each entry generates a distinct ExampleRequestItem containing its assigned identifier, summary or key name, optional description, raw request data, and encoded request data produced by encodeRequestData. If no named examples exist, a default example item is created using schema sampling or fallback heuristics. Sources: packages/openapi/src/utils/get-example-requests.ts:41-76

Parameters are iterated and assigned to distinct transport containers in getRequestData based on their in property value. Sources: packages/openapi/src/utils/get-example-requests.ts:99-130

Sources: packages/openapi/src/utils/get-example-requests.ts:117-130

Example Extraction Helpers

The helper function pickExample inspects input schemas and media objects for static examples or nested content objects, prioritizing explicit example definitions over mapped examples or sampled media types. Sources: packages/openapi/src/utils/schema.ts:32-51

Copyexport function pickExample(value: ExampleLike): unknown | undefined {
  if (value.example !== undefined) {
    return value.example;
  }
 
  if (value.content) {
    const type = getPreferredType(value.content);
    const content = type ? value.content[type] : undefined;
 
    if (type && content) {
      const out = value.examples?.[type].value ?? pickExample(content);
      if (out !== undefined) return out;
    }
  }
 
  if (value.examples) {
    const examples = Object.values(value.examples);
    if (examples.length > 0) return examples[0].value;
  }
}

Sources: packages/openapi/src/utils/schema.ts:32-51

Media Type Adapters

Encoding Handlers and Supported Formats

Fumadocs OpenAPI uses media type adapters to encode request body payloads into standard BodyInit objects for runtime requests and to translate body structures into language-specific initialization snippets. Each adapter implements the MediaAdapter interface, which mandates an encode function and a generateExample function receiving a MediaContext object. Sources: packages/openapi/src/requests/media/adapter.ts:33-58

The defaultAdapters record supports five standard media types as well as raw octet streams. Sources: packages/openapi/src/requests/media/adapter.ts:60-219

Sources: packages/openapi/src/requests/media/adapter.ts:60-219

Language Code Generation and Contexts

The str helper formats string-serializable bodies across target programming languages by inspecting ctx.lang. Supported context interfaces include GoContext, JavaScriptContext, JavaContext, and CSharpContext, which provide addImport utilities to inject required packages. Sources: packages/openapi/src/requests/media/adapter.ts:13-38, packages/openapi/src/requests/media/adapter.ts:221-258

Copyif (ctx.lang === 'js') {
  if (mediaType === 'application/json') {
    return `const body = JSON.stringify(${JSON.stringify(init, null, 2)})`;
  }
  return `const body = ${backtickQuote(inputToString(init, mediaType))}`;
}
 
if (ctx.lang === 'python') {
  return `body = ${tripleDoubleQuote(inputToString(init, mediaType))}`;
}
 
if (ctx.lang === 'go') {
  const { addImport } = ctx as GoContext;
  addImport('strings');
  return `body := strings.NewReader(${backtickQuote(inputToString(init, mediaType))})`;
}
 
if (ctx.lang === 'java') {
  const { addImport } = ctx as JavaContext;
  addImport('java.net.http.HttpRequest.BodyPublishers');
  return `var body = BodyPublishers.ofString(${tripleDoubleQuote(inputToString(init, mediaType))});`;
}
 
if (ctx.lang === 'csharp') {
  const input = `\n${inputToString(init, mediaType)}\n`;
 
  return `var body = new StringContent(${tripleDoubleQuote(input)}, Encoding.UTF8, "${mediaType}");`;
}

Sources: packages/openapi/src/requests/media/adapter.ts:230-257

Shell and Scripting Generators

cURL Invocation Generation

The curl code usage generator builds standard POSIX shell commands by assembling HTTP methods, target URLs, request headers, cookies, and payload arguments. The generator initializes the command array with the upper-case HTTP method and target URL, iterates over header entries to append -H flags, and serializes cookie parameters with --cookie flags using double quotes. Sources: packages/openapi/src/requests/generators/curl.ts:4-22

Copy  if (data.body && data.bodyMediaType === 'multipart/form-data') {
    if (typeof data.body !== 'object') throw new Error('[CURL] request body must be an object.');
 
    for (const [key, value] of Object.entries(data.body)) {
      s.push(`-F ${key}=${doubleQuote(inputToString(value))}`);
    }
  } else if (data.body && data.bodyMediaType) {
    const escaped = singleQuote(
      inputToString(
        data.body,
        // @ts-expect-error -- assume the body media type is supported
        data.bodyMediaType,
      ),
    );
 
    s.push(`-H "Content-Type: ${data.bodyMediaType}"`);
    s.push(`-d ${escaped}`);
  }
 
  return s.flatMap((v, i) => indent(v, i > 0 ? 1 : 0)).join(' \\\n');
},

Sources: packages/openapi/src/requests/generators/curl.ts:23-43

JavaScript Fetch Generation

The javascript code usage generator constructs browser-compatible fetch() API snippets, managing request configuration options, headers, cookies, and media type adaptations. It collects configuration properties in an internal Map and populates a header record with content types, custom headers, and combined cookie strings separated by semicolons. Sources: packages/openapi/src/requests/generators/javascript.ts:5-26

Copy  if (Object.keys(headers).length > 0) {
    options.set('headers', JSON.stringify(headers, null, 2));
  }
 
  let body: string | undefined;
  if (data.body && data.bodyMediaType) {
    const adapter = resolveMediaAdapter(data.bodyMediaType, mediaAdapters);
    body = adapter?.generateExample(data as { body: unknown }, {
      lang: 'js',
      addImport(from, name) {
        s.unshift(`import { ${name} } from "${from}"`);
      },
    });
  }
 
  if (body) {
    s.push(body);
    options.set('body', 'body');
  }
 
  const params = [doubleQuote(data.url)];
  if (options.size > 0) {
    const str = Array.from(options.entries())
      .map(([k, v]) => indent(k === v ? k : `${k}: ${v}`))
      .join(',\n');
 
    params.push(`{\n${str}\n}`);
  }
 
  s.push(`fetch(${params.join(', ')})`);
 
  return s.join('\n\n');
},

Sources: packages/openapi/src/requests/generators/javascript.ts:27-59

Compiled Language Generators

Go, C#, and Java Client Snippets

The compiled language generators construct strongly typed HTTP client snippets for Go, C#, and Java, mapping request configurations, headers, cookies, and media type adapters into native execution patterns. The Go generator populates an imports array with fmt, net/http, and io/ioutil, maps custom headers and cookie strings into a req.Header collection, and builds the request using http.NewRequest with http.DefaultClient.Do. Sources: packages/openapi/src/requests/generators/go.ts:5-62

Sources: packages/openapi/src/requests/generators/go.ts:9, packages/openapi/src/requests/generators/csharp.ts:10, packages/openapi/src/requests/generators/java.ts:11-18

Request Body and Media Adaptation

When a request body and bodyMediaType are present, each compiled generator resolves a media adapter to output payload examples and inject language-specific package imports into the snippet scope via the addImport callback. The Java generator configures an HttpClient builder with a 10-second connect timeout using Duration.ofSeconds(10), constructs an HttpRequest via HttpRequest.newBuilder(), appends headers and cookie strings, and invokes the dynamic HTTP method builder. Sources: packages/openapi/src/requests/generators/java.ts:21-72

Copy// Add response handling
s.push('try {');
s.push(
  indent(
    'HttpResponse<String> response = client.send(requestBuilder.build(), BodyHandlers.ofString());',
  ),
);
s.push(indent('System.out.println("Status code: " + response.statusCode());'));
s.push(indent('System.out.println("Response body: " + response.body());'));
s.push('} catch (Exception e) {');
s.push(indent('e.printStackTrace();'));
s.push('}');
 

Sources: packages/openapi/src/requests/generators/java.ts:74-86

Python Requests Generation

Constructing Python Requests Syntax

The Python requests generator builds executable HTTP request snippets using the requests library, incorporating dynamic method calls, URL strings, and dictionary literals for headers and cookies. The generator initializes an imports set with requests, evaluates any request body and media type adapter, and appends keyword arguments to a params array containing the uppercase HTTP method and target URL. Sources: packages/openapi/src/requests/generators/python.ts:5-27

Sources: packages/openapi/src/requests/generators/python.ts:9-46, packages/openapi/src/requests/generators/python.ts:72-74

Object Serialization and Type Mapping

The generatePythonObject utility recursively converts arbitrary JavaScript values into valid Python syntax literals, managing null, boolean, numeric, string, array, date, and object types. Sources: packages/openapi/src/requests/generators/python.ts:60-82

Copyif (v === null) {
  return 'None';
} else if (typeof v === 'boolean') {
  return v ? 'True' : 'False';
} else if (typeof v === 'string') {
  return doubleQuote(v);
} else if (typeof v === 'number') {
  return v.toString();
} else if (Array.isArray(v)) {
  const items = v.map((item) => generatePythonObject(item, imports));
  return `[${items.join(', ')}]`;
} else if (v instanceof Date) {
  imports.add('datetime');
  return `datetime.datetime(${v.getFullYear()}, ${v.getMonth() + 1}, ${v.getDate()}, ${v.getHours()}, ${v.getMinutes()}, ${v.getSeconds()}, ${v.getMilliseconds()})`;
} else if (typeof v === 'object') {
  const entries = Object.entries(v).map(
    ([key, value]) => `  ${doubleQuote(key)}: ${generatePythonObject(value, imports)}`,
  );
  return `{\n${entries.join(', \n')}\n}`;
} else {
  throw new Error(`Unsupported type: ${typeof v}`);
}

Sources: packages/openapi/src/requests/generators/python.ts:61-82

Related

• OpenAPI Interactive UI