Skip to content

apostrophecms/openapi-generator

BranchesTags

Repository files navigation

ApostropheCMS logo

OpenAPI Generator for ApostropheCMS

Automatically generate professional API documentation and client SDKs for your ApostropheCMS project. Discover all routes—including Pro module endpoints—and create comprehensive OpenAPI 3.1 specs with zero configuration.

Table of Contents

Why ApostropheCMS OpenAPI Generator?

  • 🎯 Your Complete API: Documents YOUR content types, custom pieces, and routes—not just core CMS
  • 🚀 Zero Configuration: Works instantly with any ApostropheCMS 4+ project
  • 🔍 Total Discovery: Automatically finds all routes, schemas, and Pro module endpoints
  • 📱 Production-Ready SDKs: Generate enterprise-grade clients in TypeScript, Python, PHP, and 20+ other languages
  • ⚡ Live Documentation: Interactive testing environment for your specific API endpoints
  • 🛠️ DevOps Ready: Built for modern development workflows and CI/CD pipelines
  • 🔧 Extensible: Custom field mappers and route filtering for project-specific needs

Requirements

  • ApostropheCMS 4.0 or higher
  • Node.js 22+
  • For SDK generation:
    • Java 8+ (required for npx or global usage)
    • Optional: global installation of @openapitools/openapi-generator-cli for faster repeat runs (uses npx by default)
    • Optional: Docker (if you prefer not to install Java). The generator will use the official openapitools/openapi-generator-cli image, which is pulled automatically the first time you run it.

Installation

npm install @apostrophecms/openapi-generator

Quick Start

  1. Add to your ApostropheCMS project: Configure the module in your app.js file:
import apostrophe from 'apostrophe';

apostrophe({
  root: import.meta,
  shortName: 'my-project',
  modules: {
    '@apostrophecms/openapi-generator': {}
  }
});
  1. Generate your OpenAPI spec:
node app openapi-generator:generate
  1. View interactive documentation:
node app openapi-generator:docs --open
  1. Generate a client SDK:
# Generate TypeScript client
node app openapi-generator:generateSDK typescript
  1. Use your generated SDK:
# Copy the generated client to your frontend/application project
cp -r generated/typescript/* ../my-frontend-app/src/api/

# Install dependencies and build (varies by language)
cd ../my-frontend-app && npm install && npm run build

How It Works

The generator uses a three-step process:

  1. Route Discovery: Scans ApostropheCMS's route registry to find all registered endpoints
  2. Schema Discovery: Examines module schemas to understand your content types
  3. Intelligent Merging: Combines discoveries with a comprehensive base specification

What Gets Discovered

Routes:

  • All core ApostropheCMS API endpoints
  • ApostropheCMS Pro module endpoints
  • Your custom piece type endpoints
  • Custom routes added via ApostropheCMS route methods (e.g. restApiRoutes(self))

Schemas:

  • Built-in piece types (User, Image, File, etc.)
  • Your custom piece types
  • Extended modules with additional fields
  • Widget schemas and field definitions

Base Specification

The generator includes a comprehensive base specification with:

  • Core API documentation
  • Complete field type definitions for all ApostropheCMS fields
  • Standard error responses and authentication schemes
  • Security configurations for all endpoints
  • Organized tag groups and parameter definitions

Your discovered content extends this base rather than replacing it.

Output Structure

Generated specs include:

  • Complete route coverage: Every endpoint in your project
  • Semantic operation IDs: listArticles, getUser, createImage
  • Logical grouping: Operations grouped by resource type
  • Rich schemas: Full property definitions with validation
  • Standard responses: Consistent error handling and success responses

Commands & Usage

Command Description Key Options
generate Generate OpenAPI specification --output=FILE, --dry-run, --routes-only, --schemas-only, --verbose
validate Validate OpenAPI specification --spec=FILE
docs Serve interactive documentation --open
generateSDK Generate client SDKs <language>, --output=DIR, --props=PROPS, --config=FILE

Basic Generation

# Generate complete OpenAPI spec (outputs to openapi/apostrophecms-openapi.yaml)
node app openapi-generator:generate

# Custom output file
node app openapi-generator:generate --output=my-api.yaml

Development & Testing

# See what routes would be discovered (no file output)
node app openapi-generator:generate --routes-only

# See what schemas would be discovered (no file output)
node app openapi-generator:generate --schemas-only

# Preview everything without writing files
node app openapi-generator:generate --dry-run

# Get detailed error information
node app openapi-generator:generate --verbose

File Validation

Once you have an OpenAPI file on disk, you can use the validate task to confirm that it is still a valid OpenAPI 3.1 specification.

This command does not regenerate or modify your spec — it only runs validation against an existing file, which is useful when:

  • You manually edited the generated spec (e.g., added custom descriptions or examples).
  • You renamed/moved the spec file and want to be sure it’s still valid before publishing it to Postman, Redoc, or other tooling.
  • You want a quick check in CI to fail the build if someone introduces an invalid change.
# Validate existing specification using either the default
node app openapi-generator:validate
# Or custom output file name
node app openapi-generator:validate --spec=custom-spec.yaml

Documentation

# Serve interactive documentation
node app openapi-generator:docs
node app openapi-generator:docs --open

Client SDK Generation

Generate type-safe client libraries in multiple languages for easy API integration.

Supported Languages

The generator supports 20+ languages, with these three built into the CLI for common use cases:

  • TypeScript: Universal for modern web frontends and Node.js backends
  • Python: Dominant in data science, automation, and content migration workflows—essential for ETL processes and AI-powered content applications
  • PHP: The web's most widely-used server-side language, powering 77% of websites—critical for existing LAMP stack integrations and legacy system migrations

SDK Requirements

The generateSDK task automatically uses npx, so in most cases you don't need to install anything extra. All you need is Java 8+ available on your system.

The generator tries multiple approaches in order of convenience:

  1. NPX (default)

    • Runs npx @openapitools/openapi-generator-cli automatically
    • Downloads the generator each time you use it
    • Works out of the box with Java 8+ installed

  2. Global install (optional) — faster repeat runs

    • Install once with: 
      npm install -g @openapitools/openapi-generator-cli
    • Also requires Java 8+
    • Speeds up subsequent SDK generations since the generator is cached locally

  3. Docker (optional) — no Java required

    • Uses the official openapitools/openapi-generator-cli Docker image
    • Great if you prefer not to install Java locally
    • Requires Docker installed and running

Check your Java installation (needed for npx or global):

java -version

If not installed, get OpenJDK 8+ from your package manager or OpenJDK.

Quick SDK Generation

# TypeScript/JavaScript client with Axios
node app openapi-generator:generateSDK typescript

# Python client
node app openapi-generator:generateSDK python

# PHP client
node app openapi-generator:generateSDK php

Advanced SDK Options

Use any OpenAPI Generator language:

# Java client with custom properties
node app openapi-generator:generateSDK java --props "groupId=com.example,artifactId=apostrophe-client"

# Go client with configuration file
node app openapi-generator:generateSDK go --config=./go-config.json

# Kotlin client
node app openapi-generator:generateSDK kotlin

What's Included in Generated SDKs

Every generated SDK comes with comprehensive documentation and features:

Rich Documentation:

  • Complete API documentation in the docs/ folder
  • Comprehensive README with examples for every endpoint
  • Language-appropriate type safety (full TypeScript definitions, Python type hints, strongly-typed clients for Go/Rust/Java)
  • Authentication helpers and error handling examples

Client Features by Language:

TypeScript / JavaScript:

  • Modern async/await with Axios HTTP client
  • Full TypeScript definitions with IntelliSense support
  • Works in both Node.js and browser environments
  • Tree-shakable imports for optimal bundle size

Python:

  • Standard Python package with pip compatibility
  • Type hints for better IDE support (where applicable)
  • Perfect for data migration scripts and ETL processes
  • Excellent for AI/ML applications working with your content

PHP:

  • Composer-friendly package structure
  • Basic type annotations and IDE autocomplete
  • Great for WordPress → ApostropheCMS migration scripts
  • Server-rendered applications and legacy system integration

Using Your Generated SDK

  1. Copy to your project:
# Copy TypeScript client
cp -r generated/typescript/* ../my-frontend-app/src/api/

# Copy Python client
cp -r generated/python/* ../my-python-app/apostrophe_client/

# Copy PHP client
cp -r generated/php/* ../my-php-app/src/ApostropheCMS/
  1. Install and build:
# TypeScript
cd ../my-frontend-app && npm install && npm run build

# Python
cd ../my-python-app && pip install -r requirements.txt

# PHP
cd ../my-php-app && composer install
  1. Use in your application:

TypeScript/JavaScript Example: TypeScript/JavaScript Example:

import 'dotenv/config';
import { Configuration, ArticlesApi, UsersApi, EventsApi } from './generated-client';

const config = new Configuration({
  basePath: process.env.APOSTROPHE_BASE_URL || 'http://localhost:3000/api/v1',
  apiKey: process.env.APOSTROPHE_API_KEY || 'your-api-key-here'
});

// Resource-scoped clients for your custom content types
const articles = new ArticlesApi(config);
const events = new EventsApi(config);
const users = new UsersApi(config);

async function run() {
  // --- Your Custom Articles ---
  // List articles with filtering
  const articleList = await articles.listArticles(1, 10);
  console.log('Articles:', articleList.data);

  // Create a new article
  const newArticle = await articles.createArticle({
    title: 'My New Article',
    body: 'Article content here...',
    tags: ['news', 'updates'],
    publishedAt: new Date().toISOString()
  });
  console.log('Created article:', newArticle.data);

  // --- Your Custom Events ---
  // Get upcoming events
  const upcomingEvents = await events.listEvents(1, 5);
  console.log('Upcoming events:', upcomingEvents.data);

  // --- Users ---
  // List users
  const userList = await users.userList();
  console.log('Users:', userList.data);
}

try {
  await run();
} catch (err: any) {
  console.error(err?.response?.data ?? err.message);
}

Python Example:

# Python
from apostrophecms_client import DefaultApi, Configuration

config = Configuration(host="https://your-apostrophe-site.com/api/v1")
api = DefaultApi(config)

articles = api.list_articles()

PHP Example:

<?php
// PHP
use ApostropheCMS\DefaultApi;
use ApostropheCMS\Configuration;

$config = new Configuration();
$config->setHost('https://your-apostrophe-site.com/api/v1');
$api = new DefaultApi($config);

$articles = $api->listArticles();

Authentication

The generated SDKs support all ApostropheCMS authentication methods:

API Keys

const config = new Configuration({
  basePath: 'http://localhost:3000/api/v1',
  apiKey: 'your-api-key-here'
});

Bearer Tokens

const config = new Configuration({
  basePath: 'http://localhost:3000/api/v1',
  accessToken: 'your-jwt-token'
});

Session-based Authentication

For browser-based applications, you can use standard session cookies alongside the API:

const config = new Configuration({
  basePath: 'http://localhost:3000/api/v1',
  withCredentials: true // Include session cookies
});

Authentication Priority:

  • API key (query string): pass apiKey into Configuration({ apiKey: '…' })
  • Bearer token: pass accessToken into Configuration({ accessToken: '…' })
  • Session/cookie: enable withCredentials and run in an environment that includes the session cookie

Security

All generated endpoints include appropriate security schemes:

security:
  - ApiKeyAuth: []
  - BearerAuth: []
  - SessionAuth: []
  - {} # Allows unauthenticated access as fallback

This provides multiple authentication options while maintaining compatibility with the ApostropheCMS authentication systems.

Configuration

The generator works without configuration, but you can customize its behavior:

// In your module configuration
'@apostrophecms/openapi-generator': {
  options: {
    // Exclude specific routes
    openapiRoutes: {
      exclude: ['debug', 'internal-test', 'admin-only']
    },

    // Custom field type mappings
    openapiFieldMappers: {
      customColor: (field) => ({
        type: 'string',
        pattern: '^#(?:[0-9a-fA-F]{3}){1,2}$',
        description: field.help || 'Hex color value'
      }),

      geoLocation: (field) => ({
        type: 'object',
        properties: {
          lat: { type: 'number', minimum: -90, maximum: 90 },
          lng: { type: 'number', minimum: -180, maximum: 180 }
        },
        required: ['lat', 'lng'],
        description: field.help || 'Geographic coordinates'
      })
    }
  }
}

Route Exclusion

Use openapiRoutes.exclude to filter out individual routes or entire resources:

openapiRoutes: {
  exclude: [
    'debug',               // Excludes any route containing this string
    'article/publish',     // Excludes specific route
    'internal'             // Excludes entire internal resource
  ]
}

Filtering Logic:

  • Partial matches: 'debug' excludes /api/v1/user/debug-stats
  • Specific routes: 'article/publish' excludes only POST /api/v1/article/{id}/publish
  • Entire resources: 'internal' excludes all internal endpoints

Custom Field Mappers

Define how custom field types should appear in the OpenAPI schema:

openapiFieldMappers: {
  // Override built-in field types
  email: (field) => ({
    type: 'string',
    format: 'email',
    pattern: '^[^@]+@[^@]+\\.[^@]+$',
    description: field.help || 'Email address with enhanced validation'
  }),

  // Handle project-specific field types
  geoLocation: (field) => ({
    type: 'object',
    properties: {
      lat: { type: 'number' },
      lng: { type: 'number' }
    },
    description: field.help || 'Geographic coordinates'
  })
}

Development Workflow

1. During Development

# Regenerate docs as you add custom fields/pieces
node app openapi-generator:generate
node app openapi-generator:docs --open  # Test your new endpoints

2. Frontend Integration

# Update your frontend client when schema changes
node app openapi-generator:generateSDK typescript
cp -r generated/typescript/* ../my-next-app/src/lib/api/
cd ../my-next-app && npm run build

3. CI/CD Integration

# Add to your deployment pipeline
node app openapi-generator:validate  # Ensure spec is valid
node app openapi-generator:generateSDK typescript --output=../frontend/src/api

4. API Testing & Validation

# Mock server for development
npm install -g @stoplight/prism-cli
prism mock openapi/apostrophecms-openapi.yaml

# Mock server runs at http://localhost:4010

Contributing

We welcome contributions to improve the generator:

  1. Fork the repository and create a feature branch
  2. Make your changes and add tests
  3. Run tests to ensure everything works
  4. Submit a pull request with a clear description

Please ensure all changes:

  • Follow existing code patterns
  • Include appropriate tests
  • Update documentation if needed
  • Work with the latest ApostropheCMS version

Community & Support

💎 Ready for Enterprise Features?

Need advanced API capabilities for your development workflow? This free OpenAPI generator works great with ApostropheCMS Pro extensions to document enterprise-grade endpoints:

🚀 ApostropheCMS Pro Features

Create an account on Apostrophe Workspaces and upgrade to ApostropheCMS Pro or contact our team to learn more about ApostropheCMS Pro licensing and unlock enterprise-grade API endpoints that will enhance your documentation and development capabilities.

Made with ❤️ by the ApostropheCMS team. Found this useful? Give us a star on GitHub! ⭐

About

No description, website, or topics provided.

Resources

Readme

License

MIT license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

1 tags

Packages

No packages published

Languages