Official Extension

OpenAPI Generator

- Maintainer: ApostropheCMS (opens in new tab)
- Last updated 7 months ago
- v1.0.0
- Open Source

README (opens in new tab)

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.

Why ApostropheCMS OpenAPI Generator?
Requirements
Installation
Quick Start
How It Works
Commands & Usage
Client SDK Generation
Authentication
Configuration
Development Workflow
Contributing
Community & Support

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

Add to your ApostropheCMS project: Configure the module in your app.js file:

      javascript   
  1 import apostrophe from 'apostrophe';  2 ​  3 apostrophe({  4   root: import.meta,  5   shortName: 'my-project',  6   modules: {  7     '@apostrophecms/openapi-generator': {}  8   }  9 });  

Generate your OpenAPI spec:

node app openapi-generator:generate

View interactive documentation:

node app openapi-generator:docs --open

Generate a client SDK:

  1 # Generate TypeScript client  2 node app openapi-generator:generateSDK typescript  

Use your generated SDK:

      bash   
  1 # Copy the generated client to your frontend/application project  2 cp -r generated/typescript/* ../my-frontend-app/src/api/  3 ​  4 # Install dependencies and build (varies by language)  5 cd ../my-frontend-app && npm install && npm run build  

How It Works

The generator uses a three-step process:

Route Discovery: Scans ApostropheCMS's route registry to find all registered endpoints
Schema Discovery: Examines module schemas to understand your content types
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

  1 # Generate complete OpenAPI spec (outputs to openapi/apostrophecms-openapi.yaml)  2 node app openapi-generator:generate  3 ​  4 # Custom output file  5 node app openapi-generator:generate --output=my-api.yaml  

Development & Testing

      bash   
  1 # See what routes would be discovered (no file output)  2 node app openapi-generator:generate --routes-only  3 ​  4 # See what schemas would be discovered (no file output)  5 node app openapi-generator:generate --schemas-only  6 ​  7 # Preview everything without writing files  8 node app openapi-generator:generate --dry-run  9 ​  10 # Get detailed error information  11 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.

  1 # Validate existing specification using either the default  2 node app openapi-generator:validate  3 # Or custom output file name  4 node app openapi-generator:validate --spec=custom-spec.yaml  

Documentation

  1 # Serve interactive documentation  2 node app openapi-generator:docs  3 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:

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

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

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

      bash   
  1 # TypeScript/JavaScript client with Axios  2 node app openapi-generator:generateSDK typescript  3 ​  4 # Python client  5 node app openapi-generator:generateSDK python  6 ​  7 # PHP client  8 node app openapi-generator:generateSDK php  

Advanced SDK Options

Use any OpenAPI Generator language:

      bash   
  1 # Java client with custom properties  2 node app openapi-generator:generateSDK java --props "groupId=com.example,artifactId=apostrophe-client"  3 ​  4 # Go client with configuration file  5 node app openapi-generator:generateSDK go --config=./go-config.json  6 ​  7 # Kotlin client  8 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

Copy to your project:

      bash   
  1 # Copy TypeScript client  2 cp -r generated/typescript/* ../my-frontend-app/src/api/  3 ​  4 # Copy Python client  5 cp -r generated/python/* ../my-python-app/apostrophe_client/  6 ​  7 # Copy PHP client  8 cp -r generated/php/* ../my-php-app/src/ApostropheCMS/  

Install and build:

      bash   
  1 # TypeScript  2 cd ../my-frontend-app && npm install && npm run build  3 ​  4 # Python  5 cd ../my-python-app && pip install -r requirements.txt  6 ​  7 # PHP  8 cd ../my-php-app && composer install  

Use in your application:

TypeScript/JavaScript Example: TypeScript/JavaScript Example:

      typescript   
  1 import 'dotenv/config';  2 import { Configuration, ArticlesApi, UsersApi, EventsApi } from './generated-client';  3 ​  4 const config = new Configuration({  5   basePath: process.env.APOSTROPHE_BASE_URL || 'http://localhost:3000/api/v1',  6   apiKey: process.env.APOSTROPHE_API_KEY || 'your-api-key-here'  7 });  8 ​  9 // Resource-scoped clients for your custom content types  10 const articles = new ArticlesApi(config);  11 const events = new EventsApi(config);  12 const users = new UsersApi(config);  13 ​  14 async function run() {  15   // --- Your Custom Articles ---  16   // List articles with filtering  17   const articleList = await articles.listArticles(1, 10);  18   console.log('Articles:', articleList.data);  19 ​  20   // Create a new article  21   const newArticle = await articles.createArticle({  22     title: 'My New Article',  23     body: 'Article content here...',  24     tags: ['news', 'updates'],  25     publishedAt: new Date().toISOString()  26   });  27   console.log('Created article:', newArticle.data);  28 ​  29   // --- Your Custom Events ---  30   // Get upcoming events  31   const upcomingEvents = await events.listEvents(1, 5);  32   console.log('Upcoming events:', upcomingEvents.data);  33 ​  34   // --- Users ---  35   // List users  36   const userList = await users.userList();  37   console.log('Users:', userList.data);  38 }  39 ​  40 try {  41   await run();  42 } catch (err: any) {  43   console.error(err?.response?.data ?? err.message);  44 }  

Python Example:

  1 # Python  2 from apostrophecms_client import DefaultApi, Configuration  3 ​  4 config = Configuration(host="https://your-apostrophe-site.com/api/v1")  5 api = DefaultApi(config)  6 ​  7 articles = api.list_articles()  

PHP Example:

  1 <?php  2 // PHP  3 use ApostropheCMS\DefaultApi;  4 use ApostropheCMS\Configuration;  5 ​  6 $config = new Configuration();  7 $config->setHost('https://your-apostrophe-site.com/api/v1');  8 $api = new DefaultApi($config);  9 ​  10 $articles = $api->listArticles();  

Authentication

The generated SDKs support all ApostropheCMS authentication methods:

API Keys

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

Bearer Tokens

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

Session-based Authentication

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

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

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:

  1 security:  2   - ApiKeyAuth: []  3   - BearerAuth: []  4   - SessionAuth: []  5   - {} # 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:

      javascript   
  1 // In your module configuration  2 '@apostrophecms/openapi-generator': {  3   options: {  4     // Exclude specific routes  5     openapiRoutes: {  6       exclude: ['debug', 'internal-test', 'admin-only']  7     },  8 ​  9     // Custom field type mappings  10     openapiFieldMappers: {  11       customColor: (field) => ({  12         type: 'string',  13         pattern: '^#(?:[0-9a-fA-F]{3}){1,2}$',  14         description: field.help || 'Hex color value'  15       }),  16 ​  17       geoLocation: (field) => ({  18         type: 'object',  19         properties: {  20           lat: { type: 'number', minimum: -90, maximum: 90 },  21           lng: { type: 'number', minimum: -180, maximum: 180 }  22         },  23         required: ['lat', 'lng'],  24         description: field.help || 'Geographic coordinates'  25       })  26     }  27   }  28 }  

Route Exclusion

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

      javascript   
  1 openapiRoutes: {  2   exclude: [  3     'debug',               // Excludes any route containing this string  4     'article/publish',     // Excludes specific route  5     'internal'             // Excludes entire internal resource  6   ]  7 }  

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:

      javascript   
  1 openapiFieldMappers: {  2   // Override built-in field types  3   email: (field) => ({  4     type: 'string',  5     format: 'email',  6     pattern: '^[^@]+@[^@]+\\.[^@]+$',  7     description: field.help || 'Email address with enhanced validation'  8   }),  9 ​  10   // Handle project-specific field types  11   geoLocation: (field) => ({  12     type: 'object',  13     properties: {  14       lat: { type: 'number' },  15       lng: { type: 'number' }  16     },  17     description: field.help || 'Geographic coordinates'  18   })  19 }  

Development Workflow

1. During Development

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

2. Frontend Integration

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

3. CI/CD Integration

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

4. API Testing & Validation

  1 # Mock server for development  2 npm install -g @stoplight/prism-cli  3 prism mock openapi/apostrophecms-openapi.yaml  4 ​  5 # Mock server runs at http://localhost:4010  

Contributing

We welcome contributions to improve the generator:

Fork the repository and create a feature branch
Make your changes and add tests
Run tests to ensure everything works
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

Discord Community - Get help from other developers
GitHub Issues - Report bugs or request features
Documentation - Comprehensive guides and API reference
Professional Support - Enterprise support and consulting

💎 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

🤖 SEO Assistant - AI-powered content optimization with dedicated API endpoints
📄 Document Versions - Complete revision management and rollback APIs
🔐 Advanced Permissions - Granular access control with user group management
🌍 Automatic Translation - Instant multilingual content generation with AI-powered translations

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! ⭐