Skip to content

Commit 2c221ab

Browse files
atextoratextor
committed
Add documentation for new Maven goal
1 parent 1da9307 commit 2c221ab

File tree

1 file changed

+119
-0
lines changed

1 file changed

+119
-0
lines changed

‎documentation/developer-guide/modules/tooling-guide/pages/maven-plugin.adoc

+119
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,7 @@ Configuration Properties:
102102

103103
== Generate Java Code for an Aspect Model
104104

105+
[[generate-domain-classes]]
105106
=== Generate Domain Classes
106107

107108
The `generateJavaClasses` goal generates Java domain classes (POJOs) for a given Aspect Model. The
@@ -161,6 +162,7 @@ are replaced using `packageName` | `String` | none | {nok}
161162
| `namePostfix` | Name postfix for generated Aspect, Entity Java classes | `String` | none | {nok}
162163
|===
163164

165+
[[generate-static-meta-classes]]
164166
=== Generate Static Meta Classes
165167

166168
The `generateStaticJavaClasses` goal generates static meta classes for a given Aspect Model. The
@@ -261,6 +263,7 @@ Configuration Properties:
261263
| `language` | The language from the model for which a JSON Schema should be generated. | `String` | en | {nok}
262264
|===
263265

266+
[[generate-openapi-specification]]
264267
== Generate an OpenAPI Specification from an Aspect Model
265268

266269
The `generateOpenApiSpec` goal generates an OpenAPI Specification for a given Aspect Model. The
@@ -375,6 +378,122 @@ Configuration Properties:
375378
| `language` | The language from the model for which an AsyncAPI specification should be generated. | `String` | en | {nok}
376379
|===
377380

381+
[[generate-api-implementation-skeleton]]
382+
== Generate an API implementation skeleton from an Aspect Model
383+
384+
The `generateAspectImplementationStub` goal generates an implementation skeleton for a given Aspect
385+
Model. It combines functionality from the xref:maven-plugin.adoc#generate-domain-classes[Java domain
386+
classes generation], the xref:maven-plugin.adoc#generate-static-meta-classes[Java static meta
387+
classes generation] and the xref:maven-plugin.adoc#generate-openapi-specification[OpenAPI
388+
specification generation]. Additionally, this goal executes the
389+
https://github.com/OpenAPITools/openapi-generator[OpenAPI generator] for the generated API
390+
description, taking into account custom configuration.
391+
392+
Usage:
393+
394+
[source,xml,subs=attributes+]
395+
----
396+
<build>
397+
<plugins>
398+
<plugin>
399+
<artifactId>esmf-aspect-model-maven-plugin</artifactId>
400+
<executions>
401+
<execution>
402+
<id>generate-openapi-spec</id>
403+
<goals>
404+
<goal>generateAspectImplementationStub</goal>
405+
</goals>
406+
</execution>
407+
</executions>
408+
<configuration>
409+
<modelsRootDirectory>$\{path-to-models-root}</modelsRootDirectory>
410+
<includes>
411+
<include>$\{urn-of-aspect-model-to-be-included}</include>
412+
</includes>
413+
<aspectApiBaseUrl>http://example.com</aspectApiBaseUrl>
414+
<outputDirectory>$\{directory-for-generated-source-files}</outputDirectory>
415+
<outputFormat>yaml</outputFormat>
416+
</configuration>
417+
</plugin>
418+
419+
<plugin>
420+
<artifactId>esmf-aspect-model-maven-plugin</artifactId>
421+
<executions>
422+
<execution>
423+
<id>generate-aspect-implementation</id>
424+
<goals>
425+
<goal>generateAspectImplementationStub</goal>
426+
</goals>
427+
<configuration>
428+
<modelsRootDirectory>$\{path-to-models-root}</modelsRootDirectory>
429+
<includes>
430+
<include>$\{urn-of-aspect-model-to-be-included}</include>
431+
</includes>
432+
<!-- this is recommended to be set to 'src-gen' -->
433+
<outputDirectory>$\{directory-for-generated-source-files}</outputDirectory>
434+
<detailedValidationMessages>true</detailedValidationMessages>
435+
<packageName>com.example</packageName>
436+
<aspectApiBaseUrl>http://example.com</aspectApiBaseUrl>
437+
<aspectResourcePath>/my-api</aspectResourcePath>
438+
<!-- optional: override the default openapi-generator version -->
439+
<openApiGeneratorVersion>${openapi-generator-maven-plugin.version}</openApiGeneratorVersion>
440+
<!-- the following configuration is only an example, using the 'spring' template -->
441+
<openApiGeneratorName>spring</openApiGeneratorName>
442+
<openApiGeneratorConfigOptions>
443+
<!-- this should match the `packageName` attribute -->
444+
<modelPackage>com.example</modelPackage>
445+
<apiPackage>com.example.api</apiPackage>
446+
<configPackage>com.example.config</configPackage>
447+
<sourceFolder>main/java</sourceFolder>
448+
<resourceFolder>main/resources</resourceFolder>
449+
<library>spring-cloud</library>
450+
<useSpringBoot3>true</useSpringBoot3>
451+
<dateLibrary>java8</dateLibrary>
452+
<useOptional>true</useOptional>
453+
<useSwaggerUI>false</useSwaggerUI>
454+
<useTags>true</useTags>
455+
<documentationProvider>none</documentationProvider>
456+
<title>MyAspect</title>
457+
</openApiGeneratorConfigOptions>
458+
</configuration>
459+
</execution>
460+
</executions>
461+
</plugin>
462+
</plugins>
463+
</build>
464+
----
465+
466+
Configuration Properties:
467+
468+
[width="100%", options="header", cols="20,50,10,10,10"]
469+
|===
470+
| Property | Description | Type | Default Value | Required
471+
| `detailedValidationMessages` | Detailed validation messages if the model can not be loaded | `Boolean` | `false` | {nok}
472+
| `modelsRootDirectory` | The path to the root directory containing the Aspect Model file(s). | `String` | `$\{basedir}/src/main/resources/aspects` | {nok}
473+
| `githubServerId` | The id of the `<server>` entry describing the GitHub repository to resolve models from. | `String` | none | {nok}
474+
| `includes` | A list of Aspect Model URNs identifying the Aspect Models to be included in the plugin execution. | `String` | none | {ok}
475+
| `outputDirectory` | The path to the directory where the generated OpenAPI Specification will be written to. | `String` | none | {ok}
476+
| `aspectApiBaseUrl` | The base URL for the Aspect API OpenAPI specification. | `String` | none | {ok}
477+
| `aspectParameterFile` | The path to a file including the schema description for the resource. For JSON the description has to be in json, for YAML it has to be in YAML. | `String` | none | {nok}
478+
| `useSemanticApiVersion` | Use the complete semantic version of the Aspect Model as the version of the Aspect API. | `Boolean` | `false` | {nok}
479+
| `aspectResourcePath` | The `resource-path` for the Aspect API endpoints. | `String` | none | {nok}
480+
| `includeQueryApi` | Include the path for the Query Aspect API Endpoint in the OpenAPI specification. | `Boolean` | `false` | {nok}
481+
| `includeFullCrud` | Include the POST/PUT/PATCH methods in the OpenAPI specification. | `Boolean` | `false` | {nok}
482+
| `includePost` | Include the POST method in the OpenAPI specification. | `Boolean` | `false` | {nok}
483+
| `includePut` | Include the PUT method in the OpenAPI specification. | `Boolean` | `false` | {nok}
484+
| `includePatch` | Include the PATCH method in the OpenAPI specification. | `Boolean` | `false` | {nok}
485+
| `excludePaging` | Exclude paging information for the Aspect API Endpoint in the OpenAPI specification. | `Boolean` | `false` | {nok}
486+
| `aspectCursorBasedPaging` | Set the used paging strategy as cursor-based paging. | `Boolean` | `false` | {nok}
487+
| `aspectOffsetBasedPaging` | Set the used paging strategy as offset-based paging. | `Boolean` | `false` | {nok}
488+
| `aspectTimeBasedPaging` | Set the used paging strategy as time-based paging. | `Boolean` | `false` | {nok}
489+
| `language` | The language from the model for which an OpenAPI specification should be generated. | `String` | en | {nok}
490+
| `templateFilePath` | The path to the file with a template for the resulting specification, including values undefined by the aspect's OpenAPI specification. The template can be in JSON or YAML format. | `String` | none | {nok}
491+
| `openApiGeneratorVersion` | The version to use for the openapi-generator-maven-plugin | `String` | 7.9.0 | {nok}
492+
| `openApiGeneratorName` | The openapi-generator template to use | `String` | none | `java` | {nok}
493+
| `openApiGeneratorConfigOptions` | The additional parameters to pass to the openapi-generator, similar to the `configOptions` attribute for openapi-generator-maven-plugin | `String` | none | {nok}
494+
| `schemaMappings` | Add additional mappings from OpenAPI schema name (i.e., Aspect Model element local name) to fully qualified Java class, in the format `Name=com.example.Name` | `String` | none | {nok}
495+
|===
496+
378497
== Generate an SQL script from an Aspect Model
379498

380499
The `generateSql` goal generates an SQL table creation script for a given Aspect Model. The default

0 commit comments

Comments
 (0)