{"_id":"@apostrophecms/openapi-generator-stable","name":"@apostrophecms/openapi-generator-stable","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@apostrophecms/openapi-generator-stable","version":"1.0.0","description":"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.","scripts":{},"keywords":["apostrophecms","cms","openapi","swagger","openapi-generator","api","documentation","specification","yaml","swagger-ui","redoc"],"license":"MIT","author":{"name":"Apostrophe Technologies, Inc."},"repository":{"type":"git","url":"git+https://github.com/apostrophecms/openapi-generator.git"},"bugs":{"url":"https://github.com/apostrophecms/openapi-generator/issues"},"homepage":"https://github.com/apostrophecms/openapi-generator#readme","type":"module","main":"index.js","exports":{".":{"import":"./index.js","require":"./index.js"}},"dependencies":{"@apidevtools/swagger-parser":"^12.0.0","@openapitools/openapi-generator-cli":"^2.31.1","express":"^5.1.0","js-yaml":"^4.1.0","open":"^10.2.0","swagger-ui-dist":"^5.29.0"},"engines":{"node":">=22"},"devDependencies":{"@stoplight/spectral-cli":"^6.15.0","eslint":"^8.57.1","eslint-config-apostrophe":"^6.0.2","eslint-plugin-import":"^2.32.0","eslint-plugin-jsdoc":"^59.0.0","eslint-plugin-node":"^11.1.0","eslint-plugin-promise":"^7.2.1","stylelint":"^16.24.0","stylelint-config-apostrophe":"^4.3.0","swagger-cli":"^4.0.4"},"gitHead":"b3e29f004f514041e1e389293ae67017c60d006e","_id":"@apostrophecms/openapi-generator-stable@1.0.0","_nodeVersion":"24.10.0","_npmVersion":"11.6.1","dist":{"integrity":"sha512-sX4nGDyPM+UtoKYk5I+bgj8USRJHr0kAb4RD6ErGmwpGbpLbwT4tvm4TSAPCGNpLocjt/4tswYGjIG2S+Shbzw==","shasum":"0cd6bbb17fe374b2ea09132804ab6c8dcc93151c","tarball":"https://registry.npmjs.org/@apostrophecms/openapi-generator-stable/-/openapi-generator-stable-1.0.0.tgz","fileCount":8,"unpackedSize":418228,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDbVwXqN7AHE41qzi4qUaBDiY6eLxAoSgiTBZOeU7j4VAIgGfe1twgllKg1ACkutgUHHP29a/xBmw6VfbauP+YjKVk="}]},"_npmUser":{"name":"boutell","email":"tom@apostrophecms.com"},"directories":{},"maintainers":[{"name":"alexgilbert","email":"alex@apostrophecms.com"},{"name":"boutell","email":"tom@apostrophecms.com"},{"name":"romanek","email":"stuart+npm@apostrophecms.com"},{"name":"bodonkey","email":"robert.means1969+apostrophecms@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/openapi-generator-stable_1.0.0_1781112810720_0.3399698455448481"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-10T17:33:30.518Z","1.0.0":"2026-06-10T17:33:30.920Z","modified":"2026-06-10T17:33:31.241Z"},"maintainers":[{"name":"alexgilbert","email":"alex@apostrophecms.com"},{"name":"boutell","email":"tom@apostrophecms.com"},{"name":"romanek","email":"stuart+npm@apostrophecms.com"},{"name":"bodonkey","email":"robert.means1969+apostrophecms@gmail.com"}],"description":"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.","homepage":"https://github.com/apostrophecms/openapi-generator#readme","keywords":["apostrophecms","cms","openapi","swagger","openapi-generator","api","documentation","specification","yaml","swagger-ui","redoc"],"repository":{"type":"git","url":"git+https://github.com/apostrophecms/openapi-generator.git"},"author":{"name":"Apostrophe Technologies, Inc."},"bugs":{"url":"https://github.com/apostrophecms/openapi-generator/issues"},"license":"MIT","readme":"
\n\n**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.\n\n---\n\n## Table of Contents\n\n- [Why ApostropheCMS OpenAPI Generator?](#why-apostrophecms-openapi-generator)\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [How It Works](#how-it-works)\n- [Commands & Usage](#commands--usage)\n- [Client SDK Generation](#client-sdk-generation)\n- [Authentication](#authentication)\n- [Configuration](#configuration)\n- [Development Workflow](#development-workflow)\n- [Contributing](#contributing)\n- [Community & Support](#community--support)\n\n---\n\n## Why ApostropheCMS OpenAPI Generator?\n\n- **🎯 Your Complete API**: Documents YOUR content types, custom pieces, and routes—not just core CMS\n- **🚀 Zero Configuration**: Works instantly with any ApostropheCMS 4+ project\n- **🔍 Total Discovery**: Automatically finds all routes, schemas, and Pro module endpoints\n- **📱 Production-Ready SDKs**: Generate enterprise-grade clients in TypeScript, Python, PHP, and 20+ other languages\n- **⚡ Live Documentation**: Interactive testing environment for your specific API endpoints\n- **🛠️ DevOps Ready**: Built for modern development workflows and CI/CD pipelines\n- **🔧 Extensible**: Custom field mappers and route filtering for project-specific needs\n\n## Requirements\n\n- ApostropheCMS 4.0 or higher\n- Node.js 22+\n- For SDK generation:\n - **Java 8+** (required for npx or global usage)\n - **Optional:** global installation of `@openapitools/openapi-generator-cli` for faster repeat runs (uses `npx` by default)\n - **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.\n\n## Installation\n\n```bash\nnpm install @apostrophecms/openapi-generator\n```\n\n## Quick Start\n\n1. **Add to your ApostropheCMS project:**\nConfigure the module in your `app.js` file:\n```javascript\nimport apostrophe from 'apostrophe';\n\napostrophe({\n root: import.meta,\n shortName: 'my-project',\n modules: {\n '@apostrophecms/openapi-generator': {}\n }\n});\n```\n\n2. **Generate your OpenAPI spec:**\n\n```bash\nnode app openapi-generator:generate\n```\n\n3. **View interactive documentation:**\n\n```bash\nnode app openapi-generator:docs --open\n```\n\n4. **Generate a client SDK:**\n\n```bash\n# Generate TypeScript client\nnode app openapi-generator:generateSDK typescript\n```\n\n5. **Use your generated SDK:**\n\n```bash\n# Copy the generated client to your frontend/application project\ncp -r generated/typescript/* ../my-frontend-app/src/api/\n\n# Install dependencies and build (varies by language)\ncd ../my-frontend-app && npm install && npm run build\n```\n\n## How It Works\n\nThe generator uses a three-step process:\n\n1. **Route Discovery**: Scans ApostropheCMS's route registry to find all registered endpoints\n2. **Schema Discovery**: Examines module schemas to understand your content types\n3. **Intelligent Merging**: Combines discoveries with a comprehensive base specification\n\n### What Gets Discovered\n\n**Routes:**\n- All core ApostropheCMS API endpoints\n- ApostropheCMS Pro module endpoints\n- Your custom piece type endpoints\n- Custom routes added via ApostropheCMS route methods (e.g. `restApiRoutes(self)`)\n\n**Schemas:**\n- Built-in piece types (User, Image, File, etc.)\n- Your custom piece types\n- Extended modules with additional fields\n- Widget schemas and field definitions\n\n### Base Specification\n\nThe generator includes a comprehensive base specification with:\n- Core API documentation\n- Complete field type definitions for all ApostropheCMS fields\n- Standard error responses and authentication schemes\n- Security configurations for all endpoints\n- Organized tag groups and parameter definitions\n\nYour discovered content extends this base rather than replacing it.\n\n### Output Structure\n\nGenerated specs include:\n\n- **Complete route coverage**: Every endpoint in your project\n- **Semantic operation IDs**: `listArticles`, `getUser`, `createImage`\n- **Logical grouping**: Operations grouped by resource type\n- **Rich schemas**: Full property definitions with validation\n- **Standard responses**: Consistent error handling and success responses\n\n## Commands & Usage\n\n| Command | Description | Key Options |\n|------------|-------------|-------------|\n| `generate` | Generate OpenAPI specification | `--output=FILE`, `--dry-run`, `--routes-only`, `--schemas-only`, `--verbose` |\n| `validate` | Validate OpenAPI specification | `--spec=FILE` |\n| `docs` | Serve interactive documentation | `--open` |\n| `generateSDK` | Generate client SDKs | ``, `--output=DIR`, `--props=PROPS`, `--config=FILE` |\n\n### Basic Generation\n\n```bash\n# Generate complete OpenAPI spec (outputs to openapi/apostrophecms-openapi.yaml)\nnode app openapi-generator:generate\n\n# Custom output file\nnode app openapi-generator:generate --output=my-api.yaml\n```\n\n### Development & Testing\n\n```bash\n# See what routes would be discovered (no file output)\nnode app openapi-generator:generate --routes-only\n\n# See what schemas would be discovered (no file output)\nnode app openapi-generator:generate --schemas-only\n\n# Preview everything without writing files\nnode app openapi-generator:generate --dry-run\n\n# Get detailed error information\nnode app openapi-generator:generate --verbose\n```\n\n### File Validation\nOnce 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**.\n\nThis command does **not** regenerate or modify your spec — it only runs validation against an existing file, which is useful when:\n\n- You manually edited the generated spec (e.g., added custom descriptions or examples).\n- You renamed/moved the spec file and want to be sure it’s still valid before publishing it to Postman, Redoc, or other tooling.\n- You want a quick check in CI to fail the build if someone introduces an invalid change.\n\n```bash\n# Validate existing specification using either the default\nnode app openapi-generator:validate\n# Or custom output file name\nnode app openapi-generator:validate --spec=custom-spec.yaml\n```\n\n### Documentation\n\n```bash\n# Serve interactive documentation\nnode app openapi-generator:docs\nnode app openapi-generator:docs --open\n```\n\n## Client SDK Generation\n\nGenerate type-safe client libraries in multiple languages for easy API integration.\n\n### Supported Languages\n\nThe generator supports 20+ languages, with these three built into the CLI for common use cases:\n\n- **TypeScript**: Universal for modern web frontends and Node.js backends\n- **Python**: Dominant in data science, automation, and content migration workflows—essential for ETL processes and AI-powered content applications\n- **PHP**: The web's most widely-used server-side language, powering 77% of websites—critical for existing LAMP stack integrations and legacy system migrations\n\n### SDK Requirements\n\nThe `generateSDK` task automatically uses **npx**, so in most cases you don't need to install anything extra.\nAll you need is **Java 8+** available on your system.\n\nThe generator tries multiple approaches in order of convenience:\n\n1. **NPX (default)**\n - Runs `npx @openapitools/openapi-generator-cli` automatically\n - Downloads the generator each time you use it\n - Works out of the box with Java 8+ installed\n\n2. **Global install (optional)** — *faster repeat runs*\n - Install once with:\n ```bash\n npm install -g @openapitools/openapi-generator-cli\n ```\n - Also requires Java 8+\n - Speeds up subsequent SDK generations since the generator is cached locally\n\n3. **Docker (optional)** — *no Java required*\n - Uses the official `openapitools/openapi-generator-cli` Docker image\n - Great if you prefer not to install Java locally\n - Requires Docker installed and running\n\n**Check your Java installation** (needed for npx or global):\n```bash\njava -version\n```\nIf not installed, get OpenJDK 8+ from your package manager or [OpenJDK](https://openjdk.org).\n\n### Quick SDK Generation\n\n```bash\n# TypeScript/JavaScript client with Axios\nnode app openapi-generator:generateSDK typescript\n\n# Python client\nnode app openapi-generator:generateSDK python\n\n# PHP client\nnode app openapi-generator:generateSDK php\n```\n\n### Advanced SDK Options\n\nUse any [OpenAPI Generator](https://openapi-generator.tech/docs/generators) language:\n\n```bash\n# Java client with custom properties\nnode app openapi-generator:generateSDK java --props \"groupId=com.example,artifactId=apostrophe-client\"\n\n# Go client with configuration file\nnode app openapi-generator:generateSDK go --config=./go-config.json\n\n# Kotlin client\nnode app openapi-generator:generateSDK kotlin\n```\n\n### What's Included in Generated SDKs\n\nEvery generated SDK comes with comprehensive documentation and features:\n\n**Rich Documentation:**\n- **Complete API documentation** in the `docs/` folder\n- **Comprehensive README** with examples for every endpoint\n- **Language-appropriate type safety** (full TypeScript definitions, Python type hints, strongly-typed clients for Go/Rust/Java)\n- **Authentication helpers** and error handling examples\n\n**Client Features by Language:**\n\n**TypeScript / JavaScript:**\n- Modern `async/await` with Axios HTTP client\n- Full TypeScript definitions with IntelliSense support\n- Works in both Node.js and browser environments\n- Tree-shakable imports for optimal bundle size\n\n**Python:**\n- Standard Python package with pip compatibility\n- Type hints for better IDE support (where applicable)\n- Perfect for data migration scripts and ETL processes\n- Excellent for AI/ML applications working with your content\n\n**PHP:**\n- Composer-friendly package structure\n- Basic type annotations and IDE autocomplete\n- Great for WordPress → ApostropheCMS migration scripts\n- Server-rendered applications and legacy system integration\n\n### Using Your Generated SDK\n\n1. **Copy to your project:**\n```bash\n# Copy TypeScript client\ncp -r generated/typescript/* ../my-frontend-app/src/api/\n\n# Copy Python client\ncp -r generated/python/* ../my-python-app/apostrophe_client/\n\n# Copy PHP client\ncp -r generated/php/* ../my-php-app/src/ApostropheCMS/\n```\n\n2. **Install and build:**\n```bash\n# TypeScript\ncd ../my-frontend-app && npm install && npm run build\n\n# Python\ncd ../my-python-app && pip install -r requirements.txt\n\n# PHP\ncd ../my-php-app && composer install\n```\n\n3. **Use in your application:**\n\n**TypeScript/JavaScript Example:**\n**TypeScript/JavaScript Example:**\n```typescript\nimport 'dotenv/config';\nimport { Configuration, ArticlesApi, UsersApi, EventsApi } from './generated-client';\n\nconst config = new Configuration({\n basePath: process.env.APOSTROPHE_BASE_URL || 'http://localhost:3000/api/v1',\n apiKey: process.env.APOSTROPHE_API_KEY || 'your-api-key-here'\n});\n\n// Resource-scoped clients for your custom content types\nconst articles = new ArticlesApi(config);\nconst events = new EventsApi(config);\nconst users = new UsersApi(config);\n\nasync function run() {\n // --- Your Custom Articles ---\n // List articles with filtering\n const articleList = await articles.listArticles(1, 10);\n console.log('Articles:', articleList.data);\n\n // Create a new article\n const newArticle = await articles.createArticle({\n title: 'My New Article',\n body: 'Article content here...',\n tags: ['news', 'updates'],\n publishedAt: new Date().toISOString()\n });\n console.log('Created article:', newArticle.data);\n\n // --- Your Custom Events ---\n // Get upcoming events\n const upcomingEvents = await events.listEvents(1, 5);\n console.log('Upcoming events:', upcomingEvents.data);\n\n // --- Users ---\n // List users\n const userList = await users.userList();\n console.log('Users:', userList.data);\n}\n\ntry {\n await run();\n} catch (err: any) {\n console.error(err?.response?.data ?? err.message);\n}\n```\n\n**Python Example:**\n```python\n# Python\nfrom apostrophecms_client import DefaultApi, Configuration\n\nconfig = Configuration(host=\"https://your-apostrophe-site.com/api/v1\")\napi = DefaultApi(config)\n\narticles = api.list_articles()\n```\n\n**PHP Example:**\n```php\nsetHost('https://your-apostrophe-site.com/api/v1');\n$api = new DefaultApi($config);\n\n$articles = $api->listArticles();\n```\n\n## Authentication\n\nThe generated SDKs support all ApostropheCMS authentication methods:\n\n### API Keys\n```javascript\nconst config = new Configuration({\n basePath: 'http://localhost:3000/api/v1',\n apiKey: 'your-api-key-here'\n});\n```\n\n### Bearer Tokens\n```javascript\nconst config = new Configuration({\n basePath: 'http://localhost:3000/api/v1',\n accessToken: 'your-jwt-token'\n});\n```\n\n### Session-based Authentication\nFor browser-based applications, you can use standard session cookies alongside the API:\n```javascript\nconst config = new Configuration({\n basePath: 'http://localhost:3000/api/v1',\n withCredentials: true // Include session cookies\n});\n```\n\n**Authentication Priority:**\n- **API key** (query string): pass `apiKey` into `Configuration({ apiKey: '…' })`\n- **Bearer token**: pass `accessToken` into `Configuration({ accessToken: '…' })`\n- **Session/cookie**: enable `withCredentials` and run in an environment that includes the session cookie\n\n### Security\n\nAll generated endpoints include appropriate security schemes:\n\n```yaml\nsecurity:\n - ApiKeyAuth: []\n - BearerAuth: []\n - SessionAuth: []\n - {} # Allows unauthenticated access as fallback\n```\n\nThis provides multiple authentication options while maintaining compatibility with the ApostropheCMS authentication systems.\n\n## Configuration\n\nThe generator works without configuration, but you can customize its behavior:\n\n```javascript\n// In your module configuration\n'@apostrophecms/openapi-generator': {\n options: {\n // Exclude specific routes\n openapiRoutes: {\n exclude: ['debug', 'internal-test', 'admin-only']\n },\n\n // Custom field type mappings\n openapiFieldMappers: {\n customColor: (field) => ({\n type: 'string',\n pattern: '^#(?:[0-9a-fA-F]{3}){1,2}$',\n description: field.help || 'Hex color value'\n }),\n\n geoLocation: (field) => ({\n type: 'object',\n properties: {\n lat: { type: 'number', minimum: -90, maximum: 90 },\n lng: { type: 'number', minimum: -180, maximum: 180 }\n },\n required: ['lat', 'lng'],\n description: field.help || 'Geographic coordinates'\n })\n }\n }\n}\n```\n\n### Route Exclusion\n\nUse `openapiRoutes.exclude` to filter out individual routes or entire resources:\n\n```javascript\nopenapiRoutes: {\n exclude: [\n 'debug', // Excludes any route containing this string\n 'article/publish', // Excludes specific route\n 'internal' // Excludes entire internal resource\n ]\n}\n```\n\n**Filtering Logic:**\n- **Partial matches**: `'debug'` excludes `/api/v1/user/debug-stats`\n- **Specific routes**: `'article/publish'` excludes only `POST /api/v1/article/{id}/publish`\n- **Entire resources**: `'internal'` excludes all internal endpoints\n\n### Custom Field Mappers\n\nDefine how custom field types should appear in the OpenAPI schema:\n\n```javascript\nopenapiFieldMappers: {\n // Override built-in field types\n email: (field) => ({\n type: 'string',\n format: 'email',\n pattern: '^[^@]+@[^@]+\\\\.[^@]+$',\n description: field.help || 'Email address with enhanced validation'\n }),\n\n // Handle project-specific field types\n geoLocation: (field) => ({\n type: 'object',\n properties: {\n lat: { type: 'number' },\n lng: { type: 'number' }\n },\n description: field.help || 'Geographic coordinates'\n })\n}\n```\n\n## Development Workflow\n\n### 1. During Development\n```bash\n# Regenerate docs as you add custom fields/pieces\nnode app openapi-generator:generate\nnode app openapi-generator:docs --open # Test your new endpoints\n```\n\n### 2. Frontend Integration\n```bash\n# Update your frontend client when schema changes\nnode app openapi-generator:generateSDK typescript\ncp -r generated/typescript/* ../my-next-app/src/lib/api/\ncd ../my-next-app && npm run build\n```\n\n### 3. CI/CD Integration\n```bash\n# Add to your deployment pipeline\nnode app openapi-generator:validate # Ensure spec is valid\nnode app openapi-generator:generateSDK typescript --output=../frontend/src/api\n```\n\n### 4. API Testing & Validation\n```bash\n# Mock server for development\nnpm install -g @stoplight/prism-cli\nprism mock openapi/apostrophecms-openapi.yaml\n\n# Mock server runs at http://localhost:4010\n```\n\n## Contributing\n\nWe welcome contributions to improve the generator:\n\n1. **Fork the repository** and create a feature branch\n2. **Make your changes** and add tests\n3. **Run tests** to ensure everything works\n4. **Submit a pull request** with a clear description\n\nPlease ensure all changes:\n- Follow existing code patterns\n- Include appropriate tests\n- Update documentation if needed\n- Work with the latest ApostropheCMS version\n\n## Community & Support\n\n- **[Discord Community](https://discord.com/invite/HwntQpADJr)** - Get help from other developers\n- **[GitHub Issues](https://github.com/apostrophecms/openapi-generator/issues)** - Report bugs or request features\n- **[Documentation](https://docs.apostrophecms.org/)** - Comprehensive guides and API reference\n- **[Professional Support](https://apostrophecms.com/contact-us)** - Enterprise support and consulting\n\n---\n\n## 💎 Ready for Enterprise Features?\n\n**Need advanced API capabilities for your development workflow?** This free OpenAPI generator works great with [**ApostropheCMS Pro**](https://apostrophecms.com/extensions?autocomplete=&license=pro) extensions to document enterprise-grade endpoints:\n\n### 🚀 **ApostropheCMS Pro Features**\n- [**🤖 SEO Assistant**](https://apostrophecms.com/extensions/seo-assistant) - AI-powered content optimization with dedicated API endpoints\n- [**📄 Document Versions**](https://apostrophecms.com/extensions/document-version) - Complete revision management and rollback APIs\n- [**🔐 Advanced Permissions**](https://apostrophecms.com/extensions/advanced-permission) - Granular access control with user group management\n- [**🌍 Automatic Translation**](https://apostrophecms.com/extensions/automatic-translation) - Instant multilingual content generation with AI-powered translations\n\n**Create an account** on Apostrophe Workspaces and upgrade to [**ApostropheCMS Pro**](https://app.apostrophecms.com/login) or **[contact our team](https://apostrophecms.com/contact-us)** to learn more about ApostropheCMS Pro licensing and unlock enterprise-grade API endpoints that will enhance your documentation and development capabilities.\n\n---\n\n
![\"ApostropheCMS](\"https://raw.githubusercontent.com/apostrophecms/apostrophe/main/logo.svg\"){kind=logo}
\n\n ![](\"https://img.shields.io/badge/MADE%20FOR%20ApostropheCMS-000000.svg?style=for-the-badge&logo=Apostrophe&labelColor=6516dd\"){kind=icon}
\n ![\"\"](\"https://img.shields.io/discord/517772094482677790?color=5865f2&label=Join%20the%20Discord&logo=discord&logoColor=fff&labelColor=000&style=for-the-badge&logoWidth=20\")
\n ![\"\"](\"https://img.shields.io/static/v1?style=for-the-badge&labelColor=000000&label=License&message=MIT&color=3DA639\")
\n