@apostrophecms/openapi-generator
Advanced tools
Automatically generate comprehensive OpenAPI 3.0 specifications for your ApostropheCMS project. Discovers routes and schemas at runtime, and outputs clean YAML for Swagger UI, Redoc, or VS Code OpenAPI tools.
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.
@openapitools/openapi-generator-cli for faster repeat runs (uses npx by default)openapitools/openapi-generator-cli image, which is pulled automatically the first time you run it.npm install @apostrophecms/openapi-generator
app.js file:import apostrophe from 'apostrophe';
apostrophe({
root: import.meta,
shortName: 'my-project',
modules: {
'@apostrophecms/openapi-generator': {}
}
});
node app openapi-generator:generate
node app openapi-generator:docs --open
# Generate TypeScript client
node app openapi-generator:generateSDK typescript
# 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
The generator uses a three-step process:
Routes:
restApiRoutes(self))Schemas:
The generator includes a comprehensive base specification with:
Your discovered content extends this base rather than replacing it.
Generated specs include:
listArticles, getUser, createImage| 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 |
# 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
# 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
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:
# 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
# Serve interactive documentation
node app openapi-generator:docs
node app openapi-generator:docs --open
Generate type-safe client libraries in multiple languages for easy API integration.
The generator supports 20+ languages, with these three built into the CLI for common use cases:
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)
npx @openapitools/openapi-generator-cli automaticallyGlobal install (optional) — faster repeat runs
npm install -g @openapitools/openapi-generator-cli
Docker (optional) — no Java required
openapitools/openapi-generator-cli Docker imageCheck your Java installation (needed for npx or global):
java -version
If not installed, get OpenJDK 8+ from your package manager or OpenJDK.
# 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
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
Every generated SDK comes with comprehensive documentation and features:
Rich Documentation:
docs/ folderClient Features by Language:
TypeScript / JavaScript:
async/await with Axios HTTP clientPython:
PHP:
# 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/
# 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
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();
The generated SDKs support all ApostropheCMS authentication methods:
const config = new Configuration({
basePath: 'http://localhost:3000/api/v1',
apiKey: 'your-api-key-here'
});
const config = new Configuration({
basePath: 'http://localhost:3000/api/v1',
accessToken: 'your-jwt-token'
});
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:
apiKey into Configuration({ apiKey: '…' })accessToken into Configuration({ accessToken: '…' })withCredentials and run in an environment that includes the session cookieAll 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.
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'
})
}
}
}
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:
'debug' excludes /api/v1/user/debug-stats'article/publish' excludes only POST /api/v1/article/{id}/publish'internal' excludes all internal endpointsDefine 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'
})
}
# Regenerate docs as you add custom fields/pieces
node app openapi-generator:generate
node app openapi-generator:docs --open # Test your new endpoints
# 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
# Add to your deployment pipeline
node app openapi-generator:validate # Ensure spec is valid
node app openapi-generator:generateSDK typescript --output=../frontend/src/api
# Mock server for development
npm install -g @stoplight/prism-cli
prism mock openapi/apostrophecms-openapi.yaml
# Mock server runs at http://localhost:4010
We welcome contributions to improve the generator:
Please ensure all changes:
Need advanced API capabilities for your development workflow? This free OpenAPI generator works great with ApostropheCMS Pro extensions to document enterprise-grade endpoints:
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! ⭐
FAQs
Automatically generate comprehensive OpenAPI 3.0 specifications for your ApostropheCMS project. Discovers routes and schemas at runtime, and outputs clean YAML for Swagger UI, Redoc, or VS Code OpenAPI tools.
We found that @apostrophecms/openapi-generator demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 7 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
The North Korean malware loader hides in a Packagist-listed package and its GitHub branch to fetch and execute remote code in a likely Contagious Interview-style lure.
Security News
The Rust project is moving toward formal rules on LLM use in contributions after months of internal debate over maintainer burden, code quality, and contributor experience.
Research
/Security News
A malicious NuGet package impersonating Sicoob exfiltrated client IDs, PFX passwords, and banking certificates through Sentry telemetry.