Skip to content

Commit

Permalink
docs(#1175): review
Browse files Browse the repository at this point in the history
  • Loading branch information
@bbortt
bbortt committed Oct 28, 2024
1 parent 652a802 commit e60da38
Show file tree
Hide file tree
Showing 2 changed files with 34 additions and 36 deletions.
10 changes: 3 additions & 7 deletions ...rus-testng/src/main/java/org/citrusframework/testng/spring/TestNGCitrusSpringSupport.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,14 +58,11 @@
/**
* Basic Citrus TestNG support base class with Spring support automatically handles test case runner creation. Also provides method parameter resolution
* and resource injection. Users can just extend this class and make use of the action runner methods provided in {@link org.citrusframework.TestActionRunner}
* and {@link GherkinTestActionRunner}. Provides Spring test listener support and
* loads basic Spring application context for Citrus.
*
* and {@link GherkinTestActionRunner}. Provides Spring test listener support and loads basic Spring application context for Citrus.
*/
@Listeners( { TestNGCitrusSpringMethodInterceptor.class } )
@ContextConfiguration(classes = {CitrusSpringConfig.class})
public class TestNGCitrusSpringSupport extends AbstractTestNGSpringContextTests
implements GherkinTestActionRunner {
public class TestNGCitrusSpringSupport extends AbstractTestNGSpringContextTests implements GherkinTestActionRunner {

/** Citrus instance */
protected Citrus citrus;
Expand Down Expand Up @@ -115,8 +112,7 @@ public void run(final IHookCallBack callBack, ITestResult testResult) {
* @param methodTestLoaders
* @param invocationCount
*/
protected void run(ITestResult testResult, Method method, List<TestLoader> methodTestLoaders,
int invocationCount) {
protected void run(ITestResult testResult, Method method, List<TestLoader> methodTestLoaders, int invocationCount) {
if (citrus == null) {
citrus = Citrus.newInstance(new CitrusSpringContextProvider(applicationContext));
CitrusAnnotations.injectCitrusFramework(this, citrus);
Expand Down
60 changes: 31 additions & 29 deletions src/manual/connector-openapi.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -322,28 +322,31 @@ The given HTTP status code defines the response that should be sent by the serve
The server will generate a proper response according to the OpenAPI specification.
This also includes a potential response message body (e.g. pet object).

[[openapi-server]]
[[openapi-test-api-generator]]
=== OpenAPI Test API Generator

For an even deeper integration with a given OpenAPI, Citrus offers the possibility to generate a dedicated Test API which provides test actions tailored to the specific operations of the OpenAPI under evaluation.
These actions can be used in XML or Java DSL.
This functionality is provided by the `Citrus OpenAPI Test API Generator` which leverages the link:https://github.com/swagger-api/swagger-codegen/tree/master[OpenAPI Code Generator] to generate code, but provides custom templates tailored for seamless integration within the Citrus framework.
The functionality is provided by the `Citrus OpenAPI Test API Generator` which leverages the link:https://github.com/swagger-api/swagger-codegen/tree/master[OpenAPI Code Generator] to generate code, but provides custom templates tailored for seamless integration within the Citrus framework.

The generator provides the following features:

* generation of a Test API
* generation of a Test API
** from OpenAPI Specification
** [TODO #1163] from WSDL via an intermediate step that generates a "light" OpenApi specification from a WSDL
* integration into <<run-xml-tests,Citrus XML test cases>>
** integration into XML editors via generated XSD
*** schema validation
*** auto completion
* integration into <<run-java,Citrus Java test cases>> via Java DSL [TODO #1161]
** [TODO #1163] from WSDL via an intermediate step that generates a "light" OpenApi specification from a WSDL
* integration into <<run-xml-tests,Citrus XML test cases>>
** integration into XML editors via generated XSD
*** schema validation
*** auto completion
* integration into <<run-java,Citrus Java test cases>> via Java DSL [TODO #1161]

The following directory structure/table specifies the files, which are generated by the generator.
Note that the `Prefix` is a configuration parameter which should uniquely identify a generated API.
It is specified in the build configuration for the Test API.
```

.Generated Folder Structure
[source]
----
target/
├───generated-test-resources/
│ ├───META-INF/
Expand All @@ -369,7 +372,7 @@ target/
│ └───MyReqTypeB.java
└───spring/
└───PrefixBeanConfiguration.java
```
----

|===
| File | Content
Expand All @@ -384,14 +387,15 @@ target/
| `PrefixBeanConfiguration.java` | A Spring @Configuration class, that registers all Test API actions as Spring beans.
|===

==== Configuration of Test API generation
==== Configuration of Test API Generation

Code generation is typically performed during the build process.
For the Citrus Test API Generator, it is carried out by a Maven or Gradle plugin.
While the standard generator plugin, `org.openapitools:openapi-generator-maven-plugin`, can be employed for this purpose, configuring it can be cumbersome, especially when dealing with multiple APIs.
To address this challenge, Citrus offers its adaptation of this standard generator plugin.
To address this challenge, Citrus offers its own adaptation of this standard generator plugin.
This `Citrus OpenAPI Generator Plugin` simplifies the configuration of test API generation by providing predefined defaults and supporting the generation of multiple APIs.
Additionally, it enhances support for generating Spring integration files (`spring.handlers` and `spring.schemas`), thereby facilitating the integration of generated APIs into Spring-based applications.
Additionally, it enhances support for generating Spring integration files (`spring.handlers` and `spring.schemas`), as described above.
It is thereby facilitating the integration of generated APIs into Spring-based applications.
Consequently, utilizing the Citrus Generator Plugin is recommended in most scenarios.

The following shows the configuration of test api generation for different scenarios:
Expand Down Expand Up @@ -537,15 +541,15 @@ These are the primary elements you can configure in the `<configuration>` sectio
|===
| Configuration element | Maven Property | Description | Default Value

| `schemaFolder` | `citrus.test.api.generator.schema.folder` | Location for the generated XSD schemas | `schema/xsd/%VERSION%`
| `resourceFolder` | `citrus.test.api.generator.resource.folder` | Location to which resources are generated | `generated-resources`
| `sourceFolder` | `citrus.test.api.generator.source.folder` | Location to which sources are generated | `generated-sources`
| `metaInfFolder` | `citrus.test.api.generator.meta.inf.folder` | Location to which spring meta files are generated/updated | `target/generated-test-resources/META-INF`
| `schemaFolder` | `citrus.test.api.generator.schema.folder` | Location of the generated XSD schemas | `schema/xsd/%VERSION%`
| `resourceFolder` | `citrus.test.api.generator.resource.folder` | Location into which the resources are generated | `generated-resources`
| `sourceFolder` | `citrus.test.api.generator.source.folder` | Location into which the sources are generated | `generated-sources`
| `metaInfFolder` | `citrus.test.api.generator.meta.inf.folder` | Location into which spring meta files are generated/updated | `target/generated-test-resources/META-INF`
| `generateSpringIntegrationFiles` | `citrus.test.api.generator.generate.spring.integration.files` | Specifies whether spring integration files should be generated | `true`
| Nested `<api />` element | | |
| `prefix` | `citrus.test.api.generator.prefix` | Specifies the prefix used for the test API, typically an acronym | (no default, required)
| `source` | `citrus.test.api.generator.source` | Specifies the source of the test API | (no default, required)
| `version` | `citrus.test.api.generator.version` | Specifies the version of the API, may be null | (none)
| `prefix` | `citrus.test.api.generator.prefix` | Specifies the prefix used for the test API, typically an acronym | (no default, **required**)
| `source` | `citrus.test.api.generator.source` | Specifies the source of the test API | (no default, **required**)
| `version` | `citrus.test.api.generator.version` | Specifies the version of the API, may be `null` | (none)
| `endpoint` | `citrus.test.api.generator.endpoint` | Specifies the endpoint of the test API | `applicationServiceClient`
| `type` | `citrus.test.api.generator.type` | Specifies the type of the test API | `REST`, other option is `SOAP`
| `useTags` | `citrus.test.api.generator.use.tags` | Specifies whether tags should be used by the generator | `true`
Expand All @@ -572,16 +576,13 @@ This command will generate the classes and XSD files as configured for your APIs
==== Spring meta file generation

The `citrus-test-api-generator-maven-plugin` supports the generation of Spring integration files, specifically `spring.handlers` and `spring.schemas`.
These files are essential for Spring applications utilizing XML configuration, as they provide mapping information for custom XML namespaces.

===== Purpose

These files are essential for Spring applications utilizing XML configuration.
The generated Spring integration files serve the purpose of mapping custom XML namespaces to their corresponding namespace handler and schema locations.
This mapping allows Spring to properly parse and validate XML configuration files containing custom elements and attributes.

===== Configuration

The maven plugin generates these Spring integration files based on the provided configuration in the `citrus-test-api-generator-maven-plugin` section of the pom.xml file.
The maven plugin generates these Spring integration files based on the provided configuration in the `citrus-test-api-generator-maven-plugin` section of the `pom.xml` file.
For each API specified, the plugin writes entries into the `spring.handlers` and `spring.schemas` files according to the configured XML namespaces and their corresponding handlers and schemas.

===== Important Consideration
Expand All @@ -607,6 +608,7 @@ This automatically happens if one of the following folders is chosen:
In case you choose to generate the API into `generated-test` folders, the maven build requires further configuration to add the `generated-test` folders to the classpath.
The link:https://www.mojohaus.org/build-helper-maven-plugin/usage.html[build-helper-maven-plugin] is used to accomplish this configuration step.

.Configuration of `build-helper-maven-plugin`
[source,xml]
----
<build>
Expand Down Expand Up @@ -649,7 +651,8 @@ The link:https://www.mojohaus.org/build-helper-maven-plugin/usage.html[build-hel

==== Sample usage

To utilize the test API in XML, it's necessary to import the respective namespace. Once imported, requests can be directly employed as actions, as illustrated in the sample below.
To utilize the test API in XML, it's necessary to import the respective namespace.
Once imported, requests can be directly employed as actions, as illustrated in the sample below.
Further examples can be found here `org.citrusframework.openapi.generator.GeneratedApiIT`.

.XML DSL
Expand Down Expand Up @@ -682,7 +685,7 @@ Further examples can be found here `org.citrusframework.openapi.generator.Genera

To utilize the test API in Java, it's necessary to import the API configuration, that provides the respective request actions.
The request to test can then be configured and autowired, as illustrated in the sample below.
Further examples can be found here `org.citrusframework.openapi.generator.GetPetByIdIT`.
Further examples can be found here: `org.citrusframework.openapi.generator.GetPetByIdIT`.

.Java DSL
[source,java,indent=0,role="secondary"]
Expand Down Expand Up @@ -715,5 +718,4 @@ class GetPetByIdTest {
runner.$(getPetByIdRequest);
}
}
----

0 comments on commit e60da38

Please sign in to comment.