apideck-codegen

name: apideck-codegen description: Generate typed API clients from Apideck OpenAPI specs using code generators. Use when the user wants to generate custom SDK clients, typed models, API stubs, or server scaffolding from Apideck's published OpenAPI specifications. Covers openapi-generator, Speakeasy, and Postman import workflows. license: Apache-2.0 alwaysApply: false metadata: author: apideck version: "1.0.0"

Apideck Code Generation Skill

Overview

Apideck publishes OpenAPI 3.x specifications for all unified APIs at https://specs.apideck.com/{api-name}.yml. These specs can be used with code generators to produce typed clients, models, server stubs, and documentation in any language.

IMPORTANT RULES

• ALWAYS prefer the official Apideck SDKs over generated clients. Code generation is for languages/frameworks not covered by official SDKs, or for custom model generation.
• ALWAYS use the latest spec from https://specs.apideck.com/{api-name}.yml. Do not use cached or outdated specs.
• USE the official SDKs for: TypeScript (@apideck/unify), Python (apideck-unify), C# (ApideckUnifySdk), Java (com.apideck:unify), Go (sdk-go), PHP (sdk-php).
• When generating clients, always configure authentication headers: Authorization, x-apideck-app-id, x-apideck-consumer-id.

Available OpenAPI Specs

All specs are also available on GitHub: https://github.com/apideck-libraries/openapi-specs

OpenAPI Generator

Installation

# npm
npm install @openapitools/openapi-generator-cli -g

# Homebrew
brew install openapi-generator

# Docker
docker pull openapitools/openapi-generator-cli

Generate a Typed Client

# TypeScript (Axios)
openapi-generator-cli generate \
  -i https://specs.apideck.com/crm.yml \
  -g typescript-axios \
  -o ./generated/crm-client \
  --additional-properties=npmName=apideck-crm,supportsES6=true,withInterfaces=true

# Python (urllib3)
openapi-generator-cli generate \
  -i https://specs.apideck.com/accounting.yml \
  -g python \
  -o ./generated/accounting-client \
  --additional-properties=packageName=apideck_accounting

# Rust
openapi-generator-cli generate \
  -i https://specs.apideck.com/crm.yml \
  -g rust \
  -o ./generated/crm-client \
  --additional-properties=packageName=apideck_crm

# Swift
openapi-generator-cli generate \
  -i https://specs.apideck.com/hris.yml \
  -g swift5 \
  -o ./generated/hris-client \
  --additional-properties=projectName=ApideckHRIS

# Kotlin
openapi-generator-cli generate \
  -i https://specs.apideck.com/crm.yml \
  -g kotlin \
  -o ./generated/crm-client \
  --additional-properties=groupId=com.apideck,artifactId=crm-client

# Dart
openapi-generator-cli generate \
  -i https://specs.apideck.com/crm.yml \
  -g dart \
  -o ./generated/crm-client

Generate Models Only

When you only need typed data models without the API client:

openapi-generator-cli generate \
  -i https://specs.apideck.com/crm.yml \
  -g typescript-axios \
  -o ./generated/crm-models \
  --global-property=models

openapi-generator-cli generate \
  -i https://specs.apideck.com/accounting.yml \
  -g python \
  -o ./generated/accounting-models \
  --global-property=models

Generate API Documentation

# HTML docs
openapi-generator-cli generate \
  -i https://specs.apideck.com/crm.yml \
  -g html2 \
  -o ./docs/crm

# Markdown docs
openapi-generator-cli generate \
  -i https://specs.apideck.com/crm.yml \
  -g markdown \
  -o ./docs/crm

Available Generators

Run openapi-generator-cli list for all generators. Common choices:

Configuration File

For repeatable generation, use a config file:

# openapitools.json
{
  "$schema": "node_modules/@openapitools/openapi-generator-cli/config.schema.json",
  "spaces": 2,
  "generator-cli": {
    "version": "7.0.0",
    "generators": {
      "crm-ts": {
        "generatorName": "typescript-axios",
        "inputSpec": "https://specs.apideck.com/crm.yml",
        "output": "./generated/crm",
        "additionalProperties": {
          "npmName": "apideck-crm",
          "supportsES6": true,
          "withInterfaces": true
        }
      },
      "accounting-py": {
        "generatorName": "python",
        "inputSpec": "https://specs.apideck.com/accounting.yml",
        "output": "./generated/accounting",
        "additionalProperties": {
          "packageName": "apideck_accounting"
        }
      }
    }
  }
}

Then run: openapi-generator-cli generate

Speakeasy

Speakeasy is the generator Apideck uses for their official SDKs.

# Install
brew install speakeasy-api/homebrew-tap/speakeasy

# Generate TypeScript SDK
speakeasy generate sdk \
  -s https://specs.apideck.com/crm.yml \
  -t typescript \
  -o ./generated/crm-sdk

# Generate Python SDK
speakeasy generate sdk \
  -s https://specs.apideck.com/accounting.yml \
  -t python \
  -o ./generated/accounting-sdk

# Generate Go SDK
speakeasy generate sdk \
  -s https://specs.apideck.com/hris.yml \
  -t go \
  -o ./generated/hris-sdk

Postman Import

Import Apideck specs directly into Postman for manual testing:

# Using Portman (recommended — adds contract tests)
npx @apideck/portman -u https://specs.apideck.com/crm.yml -o ./crm.postman.json

# Direct Postman import
# 1. Open Postman → Import → Link
# 2. Paste: https://specs.apideck.com/crm.yml
# 3. Postman auto-converts the OpenAPI spec to a collection

Filtering Specs

To generate a client for only a subset of endpoints, use oas-format-filter (used internally by Portman):

npm install -g @apideck/oas-format-filter

# Filter to only CRM contacts endpoints
oas-format-filter \
  --input https://specs.apideck.com/crm.yml \
  --output ./filtered-crm.yml \
  --filter '{"paths": ["/crm/contacts*"]}'

Then generate from the filtered spec.

Authentication Configuration

When configuring generated clients, set these headers on every request:

Authorization: Bearer {APIDECK_API_KEY}
x-apideck-app-id: {APP_ID}
x-apideck-consumer-id: {CONSUMER_ID}
x-apideck-service-id: {SERVICE_ID}  (optional, but recommended)

Base URL: https://unify.apideck.com