OpenAPI Export

Export your FakeDataDSL schemas to OpenAPI 3.0 specifications for API documentation and client generation.

Quick Start

# Export as YAML
fake_data_dsl export --all -d schemas/ -f openapi -o api.yaml

# Export as JSON
fake_data_dsl export --all -d schemas/ -f openapi -o api.json

Generated Specification

The exporter generates a complete OpenAPI 3.0 spec with:

• Info section - API title, version, description
• Server definitions - Base URLs
• Tags - One per schema for organization
• Paths - CRUD + generation endpoints
• Components/Schemas - Full schema definitions
• Parameters - Reusable query parameters

API Endpoints Generated

For each schema (e.g., User):

Method	Path	Description
GET	/api/user	Generate single record
GET	/api/user/batch	Generate multiple records
GET	/api/user/stream	Stream records (NDJSON)
POST	/api/user	Generate with overrides
GET	/api/user/schema	Get schema definition

Plus:

• GET /api/schemas - List all schemas

Ruby API

Basic Export

exporter = FakeDataDSL::Export::OpenAPI.new(registry)
yaml_spec = exporter.export

Custom Options

exporter = FakeDataDSL::Export::OpenAPI.new(
  registry,
  title: "My Data Generation API",
  version: "2.0.0",
  description: "API for generating test data",
  server_url: "https://api.example.com",
  format: :yaml
)

spec = exporter.export

Export Formats

# YAML (default)
yaml = exporter.export_as(:yaml)

# JSON
json = exporter.export_as(:json)

Configuration Options

Option	Type	Default	Description
title	String	"FakeDataDSL Data Generation API"	API title
version	String	"1.0.0"	API version
description	String	"API for generating fake data"	API description
server_url	String	"http://localhost:3000"	Base server URL
format	Symbol	:yaml	Output format (:yaml or :json)

Type Mapping

FakeDataDSL	OpenAPI
text, name, etc.	string
email	string, format: "email"
url	string, format: "uri"
uuid	string, format: "uuid"
date	string, format: "date"
timestamp, datetime	string, format: "date-time"
password	string, format: "password"
ip	string, format: "ipv4"
ipv6	string, format: "ipv6"
number, integer	integer, format: "int64"
float	number, format: "double"
boolean	boolean
binary	string, format: "binary"
array(T)	array, items: T
enum(a, b)	string, enum: ["a", "b"]

Example Output

openapi: "3.0.3"
info:
  title: FakeDataDSL Data Generation API
  version: "1.0.0"
  description: API for generating fake data from schemas
  contact:
    name: FakeDataDSL
    url: https://github.com/talaatmagdyx/fake_data_dsl

servers:
  - url: http://localhost:3000
    description: Data Generation Server

tags:
  - name: User
    description: Operations for User schema

paths:
  /api/schemas:
    get:
      tags: [Schemas]
      summary: List all available schemas
      responses:
        "200":
          description: List of schema names
          content:
            application/json:
              schema:
                type: object
                properties:
                  schemas:
                    type: array
                    items:
                      type: string

  /api/user:
    get:
      tags: [User]
      summary: Generate a single User
      parameters:
        - name: seed
          in: query
          description: Random seed for deterministic generation
          schema:
            type: integer
        - name: mode
          in: query
          description: Generation mode
          schema:
            type: string
            enum: [random, edge, invalid, hostile, mixed]
      responses:
        "200":
          description: Generated User
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"

components:
  schemas:
    User:
      type: object
      required: [id, name, email]
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        email:
          type: string
          format: email
        age:
          type: integer
          format: int64
        active:
          type: boolean
        role:
          type: string
          enum: [admin, user, moderator]

    GenerationRequest:
      type: object
      properties:
        count:
          type: integer
          default: 10
        seed:
          type: integer
        mode:
          type: string
          enum: [random, edge, invalid, hostile, mixed]
        overrides:
          type: object
          additionalProperties: true

Using Generated Spec

Swagger UI

# Serve with Swagger UI
docker run -p 8080:8080 \
  -e SWAGGER_JSON=/api.yaml \
  -v ./api.yaml:/api.yaml \
  swaggerapi/swagger-ui

Client Generation

# Generate TypeScript client
openapi-generator generate -i api.yaml -g typescript-axios -o ./client

# Generate Python client
openapi-generator generate -i api.yaml -g python -o ./client

# Generate Go client
openapi-generator generate -i api.yaml -g go -o ./client

API Testing

# Import into Postman
# 1. Open Postman
# 2. Import > File > api.yaml
# 3. All endpoints are ready to test

Integration with API Server

The OpenAPI export matches the API Server exactly:

# Start server
fake_data_dsl server schemas/ --port 3000

# Export matching spec
fake_data_dsl export --all -d schemas/ -f openapi -o api.yaml

The generated spec documents exactly what the server provides.