apideck-libraries/apideck-codegen

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

| API | Spec URL | |-----|----------| | Accounting | https://specs.apideck.com/accounting.yml | | CRM | https://specs.apideck.com/crm.yml | | HRIS | https://specs.apideck.com/hris.yml | | File Storage | https://specs.apideck.com/file-storage.yml | | ATS | https://specs.apideck.com/ats.yml | | E-commerce | https://specs.apideck.com/ecommerce.yml | | Issue Tracking | https://specs.apideck.com/issue-tracking.yml | | SMS | https://specs.apideck.com/sms.yml | | Lead | https://specs.apideck.com/lead.yml | | Vault | https://specs.apideck.com/vault.yml | | Webhook | https://specs.apideck.com/webhook.yml | | Connector | https://specs.apideck.com/connector.yml |

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:

| Language | Client Generator | Notes | |----------|-----------------|-------| | TypeScript | typescript-axios, typescript-fetch, typescript-node | typescript-axios recommended | | Python | python, python-pydantic-v1 | python uses urllib3 | | Rust | rust | Uses reqwest | | Swift | swift5, swift6 | Native URLSession | | Kotlin | kotlin, kotlin-server | Uses OkHttp | | Dart | dart, dart-dio | dart-dio for Flutter | | Ruby | ruby | Uses Faraday | | Elixir | elixir | Uses Tesla | | C++ | cpp-restsdk | Uses cpprestsdk |

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