Skip to content

Commit deecf21

Browse files
michaelbe812claude
michaelbe812
and
claude
committed
docs: add plugins section with comprehensive plugin documentation
- Add Plugins section to documentation sidebar - Create overview page explaining the plugin architecture - Add dedicated pages for each plugin: - OpenAPI Generator plugin (@nx-plugin-openapi/plugin-openapi) - hey-api plugin (@nx-plugin-openapi/plugin-hey-api) - Legacy plugin (@lambda-solutions/nx-plugin-openapi) - Include complete configuration reference for legacy plugin - Update README with links to new plugins documentation Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 3c222c2 commit deecf21

6 files changed

Lines changed: 925 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,9 @@ For comprehensive documentation, visit our [documentation site](https://berger-e
9494

9595
- [Getting Started](https://berger-engineering-io.github.io/nx-plugin-openapi/getting-started/overview/)
9696
- [Installation Guide](https://berger-engineering-io.github.io/nx-plugin-openapi/getting-started/installation/)
97+
- [Plugins Overview](https://berger-engineering-io.github.io/nx-plugin-openapi/plugins/overview/)
9798
- [Configuration Reference](https://berger-engineering-io.github.io/nx-plugin-openapi/usage/configuration/)
99+
- [Creating Custom Plugins](https://berger-engineering-io.github.io/nx-plugin-openapi/guides/creating-plugins/)
98100
- [Examples](https://berger-engineering-io.github.io/nx-plugin-openapi/usage/examples/)
99101

100102
## Features

‎apps/docs/astro.config.mjs‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,15 @@ export default defineConfig({
2626
{ label: 'Quick Start', slug: 'getting-started/quick-start' },
2727
],
2828
},
29+
{
30+
label: 'Plugins',
31+
items: [
32+
{ label: 'Overview', slug: 'plugins/overview' },
33+
{ label: 'OpenAPI Generator', slug: 'plugins/plugin-openapi' },
34+
{ label: 'hey-api', slug: 'plugins/plugin-hey-api' },
35+
{ label: '@lambda-solutions/nx-plugin-openapi', slug: 'plugins/legacy-plugin' },
36+
],
37+
},
2938
{
3039
label: 'Usage',
3140
items: [

‎apps/docs/src/content/docs/plugins/legacy-plugin.md‎

Lines changed: 363 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,363 @@
1+
---
2+
title: "@lambda-solutions/nx-plugin-openapi"
3+
description: Documentation for the original standalone Nx plugin for OpenAPI Generator
4+
---
5+
6+
# @lambda-solutions/nx-plugin-openapi
7+
8+
The original Nx Plugin for seamless integration of [OpenAPI Generator](https://openapi-generator.tech) in your Nx workspace.
9+
10+
:::note[Legacy Package]
11+
This is the original standalone plugin. For new projects, consider using the modular [`@nx-plugin-openapi/core`](/getting-started/installation/) package which provides more flexibility with multiple generator plugins.
12+
:::
13+
14+
## Features
15+
16+
- Executor for generating API clients from OpenAPI specifications
17+
- First-class Nx caching support
18+
- TypeScript Angular client generation
19+
- Works with both local and remote OpenAPI specs
20+
21+
## Installation
22+
23+
### Using nx add (Recommended)
24+
25+
The easiest way to install the plugin:
26+
27+
```bash
28+
nx add @lambda-solutions/nx-plugin-openapi
29+
```
30+
31+
This command will:
32+
- Install the plugin package
33+
- Install the required peer dependency (`@openapitools/openapi-generator-cli`)
34+
35+
### Manual Installation
36+
37+
If you prefer manual installation:
38+
39+
```bash
40+
# Install the plugin
41+
npm install --save-dev @lambda-solutions/nx-plugin-openapi
42+
43+
# Install the peer dependency
44+
npm install --save-dev @openapitools/openapi-generator-cli
45+
```
46+
47+
## Quick Start
48+
49+
### 1. Add a generate-api target
50+
51+
Add a `generate-api` target to your `project.json`:
52+
53+
```json title="project.json"
54+
{
55+
"targets": {
56+
"generate-api": {
57+
"executor": "@lambda-solutions/nx-plugin-openapi:generate-api",
58+
"options": {
59+
"inputSpec": "apps/my-app/swagger.json",
60+
"outputPath": "libs/api-client/src"
61+
}
62+
}
63+
}
64+
}
65+
```
66+
67+
### 2. Run the generator
68+
69+
```bash
70+
nx run my-app:generate-api
71+
```
72+
73+
## Configuration
74+
75+
### Required Options
76+
77+
| Option | Type | Description |
78+
|--------|------|-------------|
79+
| `inputSpec` | string | Path to the OpenAPI specification file (local file or URL) |
80+
| `outputPath` | string | Output directory for the generated client |
81+
82+
### Core Options
83+
84+
| Option | Type | Default | Description |
85+
|--------|------|---------|-------------|
86+
| `configFile` | string | - | Path to OpenAPI Generator configuration file |
87+
| `skipValidateSpec` | boolean | `false` | Skip validation of the OpenAPI specification |
88+
| `auth` | string | - | Authentication for remote specs (e.g., `bearer:token`) |
89+
90+
### Naming Options
91+
92+
| Option | Type | Description |
93+
|--------|------|-------------|
94+
| `apiNameSuffix` | string | Suffix to append to API class names |
95+
| `apiPackage` | string | Package name for API classes |
96+
| `packageName` | string | Package name for the generated library |
97+
| `modelNamePrefix` | string | Prefix for model class names |
98+
| `modelNameSuffix` | string | Suffix for model class names |
99+
| `modelPackage` | string | Package name for model classes |
100+
101+
### Project Information
102+
103+
| Option | Type | Description |
104+
|--------|------|-------------|
105+
| `artifactId` | string | Artifact ID for the generated project |
106+
| `artifactVersion` | string | Artifact version |
107+
| `groupId` | string | Group ID for Maven-style organization |
108+
109+
### Generation Behavior
110+
111+
| Option | Type | Default | Description |
112+
|--------|------|---------|-------------|
113+
| `dryRun` | boolean | `false` | Perform dry run without generating files |
114+
| `enablePostProcessFile` | boolean | `false` | Enable post-processing of files |
115+
| `minimalUpdate` | boolean | `false` | Only update changed files |
116+
| `skipOverwrite` | boolean | `false` | Don't overwrite existing files |
117+
| `removeOperationIdPrefix` | boolean | `false` | Remove operation ID prefixes |
118+
| `skipOperationExample` | boolean | `false` | Skip operation examples |
119+
| `strictSpec` | boolean | `false` | Use strict spec validation |
120+
121+
### Template Customization
122+
123+
| Option | Type | Description |
124+
|--------|------|-------------|
125+
| `templateDirectory` | string | Custom templates directory |
126+
| `ignoreFileOverride` | string | Custom ignore file path |
127+
128+
### Global Properties
129+
130+
| Option | Type | Description |
131+
|--------|------|-------------|
132+
| `globalProperties` | object | Properties passed to OpenAPI Generator |
133+
134+
### Git Integration
135+
136+
| Option | Type | Description |
137+
|--------|------|-------------|
138+
| `gitHost` | string | Git host (e.g., `github.com`) |
139+
| `gitUserId` | string | Git user/organization ID |
140+
| `gitRepoId` | string | Git repository ID |
141+
142+
### Other Options
143+
144+
| Option | Type | Description |
145+
|--------|------|-------------|
146+
| `httpUserAgent` | string | Custom HTTP user agent |
147+
| `releaseNote` | string | Release notes for generated code |
148+
| `inputSpecRootDirectory` | string | Root directory for specs |
149+
| `invokerPackage` | string | Package for invoker classes |
150+
| `logToStderr` | boolean | Log to stderr instead of stdout |
151+
152+
## Configuration Examples
153+
154+
### Basic Configuration
155+
156+
```json title="project.json"
157+
{
158+
"targets": {
159+
"generate-api": {
160+
"executor": "@lambda-solutions/nx-plugin-openapi:generate-api",
161+
"options": {
162+
"inputSpec": "apps/my-app/swagger.json",
163+
"outputPath": "libs/api-client/src"
164+
}
165+
}
166+
}
167+
}
168+
```
169+
170+
### With Global Properties
171+
172+
```json title="project.json"
173+
{
174+
"targets": {
175+
"generate-api": {
176+
"executor": "@lambda-solutions/nx-plugin-openapi:generate-api",
177+
"options": {
178+
"inputSpec": "apps/my-app/swagger.json",
179+
"outputPath": "libs/api-client/src",
180+
"globalProperties": {
181+
"supportsES6": "true",
182+
"npmName": "@my-org/api-client",
183+
"npmVersion": "1.0.0",
184+
"providedInRoot": "true",
185+
"withInterfaces": "true",
186+
"useSingleRequestParameter": "true"
187+
}
188+
}
189+
}
190+
}
191+
}
192+
```
193+
194+
### Using a Configuration File
195+
196+
```json title="apps/my-app/openapi-config.json"
197+
{
198+
"npmName": "@my-org/api-client",
199+
"npmVersion": "1.0.0",
200+
"ngVersion": "17.0.0",
201+
"providedInRoot": true,
202+
"withInterfaces": true,
203+
"useSingleRequestParameter": true,
204+
"supportsES6": true,
205+
"modelPropertyNaming": "camelCase",
206+
"enumPropertyNaming": "UPPERCASE"
207+
}
208+
```
209+
210+
```json title="project.json"
211+
{
212+
"targets": {
213+
"generate-api": {
214+
"executor": "@lambda-solutions/nx-plugin-openapi:generate-api",
215+
"options": {
216+
"inputSpec": "apps/my-app/swagger.json",
217+
"outputPath": "libs/api-client/src",
218+
"configFile": "apps/my-app/openapi-config.json"
219+
}
220+
}
221+
}
222+
}
223+
```
224+
225+
### Remote OpenAPI Specification
226+
227+
```json title="project.json"
228+
{
229+
"targets": {
230+
"generate-api": {
231+
"executor": "@lambda-solutions/nx-plugin-openapi:generate-api",
232+
"options": {
233+
"inputSpec": "https://api.example.com/v1/swagger.json",
234+
"outputPath": "libs/api-client/src",
235+
"auth": "bearer:your-api-token"
236+
}
237+
}
238+
}
239+
}
240+
```
241+
242+
### Environment-Specific Configurations
243+
244+
```json title="project.json"
245+
{
246+
"targets": {
247+
"generate-api": {
248+
"executor": "@lambda-solutions/nx-plugin-openapi:generate-api",
249+
"options": {
250+
"inputSpec": "apps/my-app/swagger.json",
251+
"outputPath": "libs/api-client/src"
252+
},
253+
"configurations": {
254+
"development": {
255+
"inputSpec": "http://localhost:3000/api/swagger.json",
256+
"skipValidateSpec": true
257+
},
258+
"production": {
259+
"inputSpec": "https://api.prod.example.com/swagger.json",
260+
"strictSpec": true
261+
}
262+
}
263+
}
264+
}
265+
}
266+
```
267+
268+
Run with a specific configuration:
269+
270+
```bash
271+
nx run my-app:generate-api:development
272+
```
273+
274+
## Nx Caching
275+
276+
The plugin fully supports Nx's caching system. Generated output is cached based on:
277+
278+
- The OpenAPI specification file content
279+
- All configuration options
280+
- Plugin version
281+
282+
To enable caching in CI, configure [Nx Cloud](https://nx.app/) or local caching.
283+
284+
## Verification
285+
286+
After installation, verify the plugin is working:
287+
288+
```bash
289+
nx list @lambda-solutions/nx-plugin-openapi
290+
```
291+
292+
Expected output:
293+
294+
```
295+
@lambda-solutions/nx-plugin-openapi
296+
297+
Executors:
298+
- generate-api : Generate API client code from OpenAPI specifications
299+
```
300+
301+
## Troubleshooting
302+
303+
### Java Not Found
304+
305+
OpenAPI Generator requires Java 8+:
306+
307+
```bash
308+
java -version
309+
```
310+
311+
If Java isn't installed, download it from [adoptium.net](https://adoptium.net/).
312+
313+
### Spec Validation Errors
314+
315+
Skip validation if needed:
316+
317+
```json
318+
{
319+
"skipValidateSpec": true
320+
}
321+
```
322+
323+
### Caching Issues
324+
325+
Clear the Nx cache if you encounter stale output:
326+
327+
```bash
328+
nx reset
329+
```
330+
331+
## Migration to Modular Architecture
332+
333+
To migrate to the new modular architecture:
334+
335+
1. Install the new packages:
336+
```bash
337+
npm install --save-dev @nx-plugin-openapi/core @nx-plugin-openapi/plugin-openapi
338+
```
339+
340+
2. Update your executor:
341+
```json
342+
{
343+
"executor": "@nx-plugin-openapi/core:generate-api",
344+
"options": {
345+
"generator": "openapi-tools",
346+
// ... other options remain the same
347+
}
348+
}
349+
```
350+
351+
3. Optionally remove the legacy package:
352+
```bash
353+
npm uninstall @lambda-solutions/nx-plugin-openapi
354+
```
355+
356+
## Support
357+
358+
- [GitHub Issues](https://github.com/berger-engineering-io/nx-plugin-openapi/issues) - Report bugs and request features
359+
- [Documentation](https://berger-engineering-io.github.io/nx-plugin-openapi/) - Full documentation site
360+
361+
## License
362+
363+
MIT

0 commit comments

Comments
 (0)