diff --git a/core/citrus-api/src/main/java/org/citrusframework/testapi/GeneratedApi.java b/core/citrus-api/src/main/java/org/citrusframework/testapi/GeneratedApi.java index b48861b635..a3d6bfdad2 100644 --- a/core/citrus-api/src/main/java/org/citrusframework/testapi/GeneratedApi.java +++ b/core/citrus-api/src/main/java/org/citrusframework/testapi/GeneratedApi.java @@ -2,25 +2,44 @@ import java.util.Map; +/** + * Interface representing a generated API from an OpenAPI specification. + * Provides methods to retrieve metadata about the API such as title, version, + * prefix, and information extensions. + */ public interface GeneratedApi { /** - * @return the title of the open api + * Retrieves the title of the OpenAPI specification, as specified in the info section of the API. + * + * @return the title of the OpenAPI specification */ String getApiTitle(); /** - * @return the version of the open api + * Retrieves the version of the OpenAPI specification, as specified in the info section of the API. + * + * @return the version of the OpenAPI specification */ String getApiVersion(); /** - * @return the prefix used for the api + * Retrieves the prefix used for the API, as specified in the API generation configuration. + * + * @return the prefix used for the API */ String getApiPrefix(); /** - * @return the info extensions of the api + * Retrieves the specification extensions of the OpenAPI defined in the "info" section. + *

+ * Specification extensions, also known as vendor extensions, are custom key-value pairs used to describe extra + * functionality not covered by the standard OpenAPI Specification. These properties start with "x-". + * This method collects only the extensions defined in the "info" section of the API. + *

+ * + * @return a map containing the specification extensions defined in the "info" section of the API, + * where keys are extension names and values are extension values */ Map getApiInfoExtensions(); -} +} \ No newline at end of file diff --git a/core/citrus-api/src/main/java/org/citrusframework/testapi/GeneratedApiRequest.java b/core/citrus-api/src/main/java/org/citrusframework/testapi/GeneratedApiRequest.java index 9e588bd60b..5b519ac118 100644 --- a/core/citrus-api/src/main/java/org/citrusframework/testapi/GeneratedApiRequest.java +++ b/core/citrus-api/src/main/java/org/citrusframework/testapi/GeneratedApiRequest.java @@ -1,17 +1,28 @@ package org.citrusframework.testapi; +/** + * Interface representing a generated API request corresponding to an operation in an OpenAPI specification. + * Provides methods to retrieve metadata about the request such as operation name, HTTP method, and path. + */ public interface GeneratedApiRequest { + /** - * @return the name of the open api operation + * Retrieves the name of the OpenAPI operation associated with the request. + * + * @return the name of the OpenAPI operation */ String getOperationName(); /** - * @return the http method used for the request + * Retrieves the HTTP method used for the request. + * + * @return the HTTP method used for the request (e.g., GET, POST) */ String getMethod(); /** + * Retrieves the path used for the request. + * * @return the path used for the request */ String getPath(); diff --git a/pom.xml b/pom.xml index 8ffc43ad17..981380096e 100644 --- a/pom.xml +++ b/pom.xml @@ -175,6 +175,7 @@ 1.6.13 3.9.0 3.12.0 + 3.3.0 3.0.1 3.3.1 1.11.2 @@ -247,12 +248,14 @@ 3.1.0 4.1.105.Final 4.12.0 + 7.5.0 4.7.5 3.0.3 4.19.1 2.0.11 1.1.10.5 2.2 + 3.2.5 6.1.6 4.0.10 6.2.4 @@ -512,6 +515,13 @@ ${wsdl4j.version} + + org.openapitools + openapi-generator + ${openapi-generator-maven-plugin} + provided + + org.springframework spring-test @@ -860,6 +870,11 @@ jackson-databind ${jackson.version} + + com.fasterxml.jackson.dataformat + jackson-dataformat-yaml + ${jackson.version} + com.fasterxml.jackson.module jackson-module-jaxb-annotations diff --git a/src/manual/connector-openapi.adoc b/src/manual/connector-openapi.adoc index 53333ff1f0..b89f3889c2 100644 --- a/src/manual/connector-openapi.adoc +++ b/src/manual/connector-openapi.adoc @@ -309,3 +309,401 @@ Also, the server will verify the HTTP request method, the Content-Type header as The given HTTP status code defines the response that should be sent by the server. 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 + +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 generator provides the following features: + +* 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 Citrus XML test cases +** integration into XML editors via generated XSD +*** schema validation +*** auto completion +* integration into 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. +``` +target/ +├───generated-test-resources/ +│ ├───META-INF/ +│ │ ├───spring.handlers +│ │ └───spring.schemas +│ └───schema/ +│ └───xsd/ +│ └───prefix-api.xsd +└───generated-test-sources/ + └───org/ + └───citrusframework/ + └───automation/ + └───prefix/ + ├───api/ + │ └───MyApi.java + ├───citrus/ + │ ├───extension/ + │ │ └───PrefixNamespaceHandler.java + │ ├───PrefixAbstractTestRequest.java + │ └───PrefixBeanDefinitionParser.java + ├───model/ + │ ├───MyReqTypeA.java + │ └───MyReqTypeB.java + └───spring/ + └───PrefixBeanConfiguration.java +``` + +|=== +| File | Content + +| `spring.handlers` | Spring namespace handler configuration, that contains all NamespaceHandlers for all generated APIs. +| `spring.schemas` | Spring schema definitions, with mappings of namespaces to schemas for all generated APIs. +| `prefix-api.xsd` | XSD schema for the integration of the Test API into XML. +| `PrefixNamespaceHandler.java` | A Spring class, that registers bean definition parsers for Test API XML elements. +| `PrefixAbstractTestRequest.java` | Abstract superclass of all Test API actions. +| `PrefixBeanDefinitionParser.java` | Spring bean definition parser, responsible for parsing Test API XML elements into test actions. +| `MyReqTypeA.java, MyReqTypeB.java` | Model files generated with respect to the schema definition of the OpenAPI. +| `PrefixBeanConfiguration.java` | A Spring @Configuration class, that registers all Test API actions as Spring beans. +|=== + +==== 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 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 Maven 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. +Consequently, utilizing the Citrus Generator Plugin is recommended in most scenarios. + +The following shows the configuration of test api generation for different scenarios: + +.Citrus OpenAPI Generator Plugin - multiple APIs, minimal configuration +[source,xml,indent=0,role="primary"] +---- + + citrus-test-api-generator-maven-plugin + + + + + Multi1 + api/test-api.yml + + + Multi2 + api/test-api.yml + + + Multi3 + api/test-api.yml + + + + + + + create-test-api + + + + + +---- + +.Citrus OpenAPI Generator Plugin - single API full configuration +[source,xml,indent=0,role="secondary"] +---- + + citrus-test-api-generator-maven-plugin + + + + my-generated-sources + my-generated-resources + myschema/xsd + src/main/resources/META-INF + + Full + api/test-api.yml + org.mypackage.%PREFIX%.api + myEndpoint + org.mypackage.%PREFIX%.invoker + org.mypackage.%PREFIX%.model + "http://company/citrus-test-api/myNamespace" + + + + + + + + create-test-api + + + + +---- + +.Standard OpenAPI Generator Plugin +[source,xml,indent=0,role="secondary"] +---- + + + org.openapitools + openapi-generator-maven-plugin + + + + org.citrusframework + citrus-test-api-generator-core + ${project.version} + + + + + REST + generated-test-resources + generated-test-sources + true + + true + + java-citrus + ${project.build.directory} + + + + generate-openapi-petstore-files + compile + + generate + + + ${project.basedir}/src/test/resources/apis/petstore.yaml + + org.citrusframework.openapi.generator.rest.petstore + org.citrusframework.openapi.generator.rest.petstore.request + org.citrusframework.openapi.generator.rest.petstore.model + PetStore + petStoreEndpoint + + + + + generate-openapi-files-for-soap + compile + + generate + + + ${project.basedir}/src/test/resources/org/citrusframework/openapi/generator/SimpleWsdlToOpenApiTransformerTest/BookService-generated.yaml + + SOAP + org.citrusframework.openapi.generator.soap.bookservice + org.citrusframework.openapi.generator.soap.bookservice.request + org.citrusframework.openapi.generator.soap.bookservice.model + SoapSample + OpenApiFromWsdl + soapSampleEndpoint + + + + + +---- + +These are the primary elements you can configure in the `` section: + +|=== +| 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` +| `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) +| `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` +| `invokerPackage` | `citrus.test.api.generator.invoker.package` | Package for the test API classes | `org.citrusframework.automation.%PREFIX%.%VERSION%` +| `apiPackage` | `citrus.test.api.generator.api.package` | Package for the test API interface classes | `org.citrusframework.automation.%PREFIX%.%VERSION%.api` +| `modelPackage` | `citrus.test.api.generator.model.package` | Package for the test API model classes | `org.citrusframework.automation.%PREFIX%.%VERSION%.model` +| `targetXmlnsNamespace` | `citrus.test.api.generator.namespace` | XML namespace used by the API | `http://www.citrusframework.org/schema/%VERSION%/%PREFIX%-api` +|=== + + +Note: `%PREFIX%` and `%VERSION%` are placeholders that will be replaced by their specific values as configured. +The plugin performs a conversion to lowercase for `PREFIX` used in package names and in `targetXmlnsNamespace`. + +==== Running the generator + +To run the generator, execute the following command in your project directory: + +[source,bash] +---- +mvn citrus-test-api-generator-maven-plugin:create-test-api +---- + + +This command will generate the classes and XSD files as configured for your APIs in the specified locations. + +==== 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 + +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. +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 + +When there are other non-generated Spring schemas or handlers present in the `META-INF` folder, it's crucial to ensure that the `metaInfFolder` configuration points to the existing `META-INF` directory in the main resources, which is usually `src/main/resources/META-INF`. +This ensures that the plugin correctly updates the existing files without overwriting them. + +To identify generated schemas, their namespace should include the following segment `citrus-test-schema`. +During updates of the meta files, the generator filters out lines containing this segment from existing files and then re-adds them, preserving any non-generated content. + +==== Usage + +Once generated, the `spring.handlers` and `spring.schemas` files, along with any existing non-generated content, should be included in the resources of your Spring application. +During runtime, Spring will use these files to resolve custom XML namespaces and handle elements accordingly. +This automatically happens if one of the following folders is chosen: + +- `target/generated-test-resources/META-INF` (default) +- `target/generated-resources/META-INF` for pure testing projects that provide their code on main rather than test +- `src/main/resources/META-INF` - for mixing existing meta files with generated + +==== Configuration of the Test Classpath + +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. + +[source,xml] +---- + + + + org.codehaus.mojo + build-helper-maven-plugin + + + add-test-sources + generate-test-sources + + add-test-source + + + + ${project.build.directory}/generated-test-sources + + + + + add-test-resource + generate-test-resources + + add-test-resource + + + + + ${project.build.directory}/generated-test-resources + + + + + + + + +---- + +==== 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. +Further examples can be found here `org.citrusframework.openapi.generator.GeneratedApiIT`. + +.XML DSL +[source,xml,indent=0,role="secondary"] +---- + + + + + + + + + + + + +---- + +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 autowired, configured and autowired, as illustrated in the sample below. +Further examples can be found here `org.citrusframework.openapi.generator.GetPetByIdTest`. + +.Java DSL +[source,java,indent=0,role="secondary"] +---- +@ExtendWith(CitrusSpringExtension.class) +@SpringBootTest(classes = {PetStoreBeanConfiguration.class, CitrusSpringConfig.class}) +class GetPetByIdTest { + + @Autowired + private ApplicationContext applicationContext; + + @Autowired + private GetPetByIdRequest getPetByIdRequest; + + @Test + @CitrusTest + void testByJsonPath(@CitrusResource TestCaseRunner runner) { + + // Given + getPetByIdRequest.setPetId("1234"); + + // Then + getPetByIdRequest.setResponseStatus(HttpStatus.OK.value()); + getPetByIdRequest.setResponseReasonPhrase(HttpStatus.OK.getReasonPhrase()); + + // Assert body by json path + getPetByIdRequest.setResponseValue(Map.of("$.name", "Snoopy")); + + // When + runner.$(getPetByIdRequest); + } +} + +---- diff --git a/src/manual/index.adoc b/src/manual/index.adoc index 9ae7fccb18..9d4c2ec4a0 100644 --- a/src/manual/index.adoc +++ b/src/manual/index.adoc @@ -62,6 +62,8 @@ include::endpoint-restdocs.adoc[] include::endpoint-component.adoc[] include::endpoint-adapter.adoc[] +include::testapi.adoc[] + include::connectors.adoc[] include::functions.adoc[] diff --git a/src/manual/testapi.adoc b/src/manual/testapi.adoc deleted file mode 100644 index f7d7cc7add..0000000000 --- a/src/manual/testapi.adoc +++ /dev/null @@ -1,380 +0,0 @@ -[[testapi]] -= Test API Generation - -== OpenAPI: A Standard for API Description -OpenAPI, formerly known as Swagger, is a widely adopted standard for describing RESTful APIs. It provides a -language-agnostic interface to define the structure of APIs in a human-readable format, typically using YAML -or JSON. OpenAPI specifications serve as a contract for your API, detailing endpoints, request/response formats, -authentication methods, and more. - -OpenAPI specifications are commonly used to generate various artifacts such as client libraries, server stubs, and -documentation. By capturing the structure and behavior of APIs in a machine-readable format, OpenAPI enables -seamless code generation, saving time and ensuring consistency across different implementations. - -== Introducing the Citrus OpenAPI Test API Generator - -Given the widespread adoption of OpenAPI code generation in service implementation, it's natural to extend -this practice to testing. The `Citrus OpenAPI Test API Generator` leverages OpenAPI specifications -to craft a dedicated test API explicitly designed for testing the API under evaluation. This tailored API -seamlessly integrates into Citrus XML or Java tests, ensuring a cohesive testing experience. - -== What does it offer? - -`Citrus OpenAPI Test API Generator` provides the following features: - -* 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 Citrus XML test cases -** integration into XML editors via provided XSD -*** schema validation -*** auto completion -* integration into Citrus Java test cases - -=== How Does it Work? - -The `Citrus OpenAPI Test API Generator` 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. - -During a build process, code generation is carried out by a Maven 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 Maven 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. Consequently, utilizing the -Citrus Generator Plugin is recommended in most scenarios. - -The following shows the configuration of test api generation for different scenarios: - -.Citrus OpenAPI Generator Plugin - multiple APIs, minimal configuration -[source,xml,indent=0,role="primary"] ----- - - citrus-test-api-generator-maven-plugin - - - - - Multi1 - api/test-api.yml - - - Multi2 - api/test-api.yml - - - Multi3 - api/test-api.yml - - - - - - - create-test-api - - - - - ----- - -.Citrus OpenAPI Generator Plugin - single API full configuration -[source,xml,indent=0,role="secondary"] ----- - - citrus-test-api-generator-maven-plugin - - - - my-generated-sources - my-generated-resources - myschema/xsd - src/main/resources/META-INF - - Full - api/test-api.yml - org.mypackage.%PREFIX%.api - myEndpoint - org.mypackage.%PREFIX%.invoker - org.mypackage.%PREFIX%.model - "http://company/citrus-test-api/myNamespace" - - - - - - - - create-test-api - - - - ----- - -.Standard OpenAPI Generator Plugin -[source,xml,indent=0,role="secondary"] ----- - - - org.openapitools - openapi-generator-maven-plugin - - - - org.citrusframework - citrus-test-api-generator-core - ${project.version} - - - - - REST - generated-test-resources - generated-test-sources - true - - true - - java-citrus - ${project.build.directory} - - - - generate-openapi-petstore-files - compile - - generate - - - ${project.basedir}/src/test/resources/apis/petstore.yaml - - org.citrusframework.openapi.generator.rest.petstore - org.citrusframework.openapi.generator.rest.petstore.request - org.citrusframework.openapi.generator.rest.petstore.model - PetStore - petStoreEndpoint - - - - - generate-openapi-files-for-soap - compile - - generate - - - ${project.basedir}/src/test/resources/org/citrusframework/openapi/generator/SimpleWsdlToOpenApiTransformerTest/BookService-generated.yaml - - SOAP - org.citrusframework.openapi.generator.soap.bookservice - org.citrusframework.openapi.generator.soap.bookservice.request - org.citrusframework.openapi.generator.soap.bookservice.model - SoapSample - OpenApiFromWsdl - soapSampleEndpoint - - - - - ----- - -=== Configuration Options - -Here are the primary elements you can configure in the `` section: - -|=== -| 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` -| `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) -| `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` -| `invokerPackage` | `citrus.test.api.generator.invoker.package` | Package for the test API classes | `org.citrusframework.automation.%PREFIX%.%VERSION%` -| `apiPackage` | `citrus.test.api.generator.api.package` | Package for the test API interface classes | `org.citrusframework.automation.%PREFIX%.%VERSION%.api` -| `modelPackage` | `citrus.test.api.generator.model.package` | Package for the test API model classes | `org.citrusframework.automation.%PREFIX%.%VERSION%.model` -| `targetXmlnsNamespace` | `citrus.test.api.generator.namespace` | XML namespace used by the API | `http://www.citrusframework.org/schema/%VERSION%/%PREFIX%-api` -|=== - - -Note: `%PREFIX%` and `%VERSION%` are placeholders that will be replaced by their specific values as configured. The plugin performs a conversion to lowercase for `PREFIX` used in package names and in `targetXmlnsNamespace`. - -=== Running the generator - -To run the generator, execute the following command in your project directory: - -[source,bash] ----- -mvn citrus-test-api-generator-maven-plugin:create-test-api ----- - - -This command will generate the classes and XSD files as configured for your APIs in the specified locations. - -=== 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 - -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 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 - -When there are other non-generated Spring schemas or handlers present in the `META-INF` folder, it's crucial to ensure that the `metaInfFolder` -configuration points to the existing `META-INF` directory in the main resources, which is usually `src/main/resources/META-INF`. This ensures -that the plugin correctly updates the existing files without overwriting them. - -To identify generated schemas, their namespace should include the following segment `citrus-test-schema`. During updates of the meta files, -the generator filters out lines containing this segment from existing files and then re-adds them, preserving any non-generated content. - -==== Usage - -Once generated, the `spring.handlers` and `spring.schemas` files, along with any existing non-generated content, should be included in the -resources of your Spring application. During runtime, Spring will use these files to resolve custom XML namespaces and handle elements accordingly. -This automatically happens if one of the following folders is chosen: - -- `target/generated-test-resources/META-INF` (default) -- `target/generated-resources/META-INF` for pure testing projects that provide their code on main rather than test -- `src/main/resources/META-INF` - for mixing existing meta files with generated - -=== Configuration of the Test Classpath - -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. - -[source,xml] ----- - - - - org.codehaus.mojo - build-helper-maven-plugin - - - add-test-sources - generate-test-sources - - add-test-source - - - - ${project.build.directory}/generated-test-sources - - - - - add-test-resource - generate-test-resources - - add-test-resource - - - - - ${project.build.directory}/generated-test-resources - - - - - - - - ----- - -=== 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. Further examples can be found here -`org.citrusframework.openapi.generator.GeneratedApiIT`. - - - -.XML DSL -[source,xml,indent=0,role="secondary"] ----- - - - - - - - - - - - - ----- - - -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 autowired, configured and autowired, as illustrated in the sample below. -Further examples can be found here `org.citrusframework.openapi.generator.GetPetByIdTest`. - -.Java DSL -[source,java,indent=0,role="secondary"] ----- -@ExtendWith(CitrusSpringExtension.class) -@SpringBootTest(classes = {PetStoreBeanConfiguration.class, CitrusSpringConfig.class}) -class GetPetByIdTest { - - @Autowired - private ApplicationContext applicationContext; - - @Autowired - private GetPetByIdRequest getPetByIdRequest; - - @Test - @CitrusTest - void testByJsonPath(@CitrusResource TestCaseRunner runner) { - - // Given - getPetByIdRequest.setPetId("1234"); - - // Then - getPetByIdRequest.setResponseStatus(HttpStatus.OK.value()); - getPetByIdRequest.setResponseReasonPhrase(HttpStatus.OK.getReasonPhrase()); - - // Assert body by json path - getPetByIdRequest.setResponseValue(Map.of("$.name", "Snoopy")); - - // When - runner.$(getPetByIdRequest); - } -} - ----- diff --git a/test-api-generator/citrus-test-api-generator-core/pom.xml b/test-api-generator/citrus-test-api-generator-core/pom.xml index c6366b98ee..c74f91249a 100644 --- a/test-api-generator/citrus-test-api-generator-core/pom.xml +++ b/test-api-generator/citrus-test-api-generator-core/pom.xml @@ -20,46 +20,47 @@ - org.openapitools - openapi-generator - 7.5.0 - provided - - - - wsdl4j - wsdl4j - 1.6.3 + org.citrusframework + citrus-api + ${project.version} - - com.fasterxml.jackson.dataformat - jackson-dataformat-yaml - ${jackson.version} + org.citrusframework + citrus-http + ${project.version} org.citrusframework - citrus-api - 4.3.0-SNAPSHOT + citrus-spring + ${project.version} + test org.citrusframework - citrus-http - 4.3.0-SNAPSHOT + citrus-ws + ${project.version} + org.assertj assertj-core - 3.25.1 + ${assertj.version} test - - org.citrusframework - citrus-spring - ${project.version} - test + com.fasterxml.jackson.dataformat + jackson-dataformat-yaml + + + org.openapitools + openapi-generator + + + wsdl4j + wsdl4j + + org.citrusframework citrus-junit5 @@ -69,26 +70,15 @@ org.springframework.boot spring-boot-test - 3.2.5 + ${spring.boot.test.version} test - - org.citrusframework - citrus-ws - ${project.version} - org.citrusframework citrus-validation-json ${project.version} test - - org.junit.jupiter - junit-jupiter-params - 5.10.2 - test - @@ -96,7 +86,7 @@ org.codehaus.mojo build-helper-maven-plugin - 3.5.0 + ${maven.helper.plugin.version} add-generated-specs diff --git a/test-api-generator/citrus-test-api-generator-maven-plugin/pom.xml b/test-api-generator/citrus-test-api-generator-maven-plugin/pom.xml index c862ef272d..e92fd84d94 100644 --- a/test-api-generator/citrus-test-api-generator-maven-plugin/pom.xml +++ b/test-api-generator/citrus-test-api-generator-maven-plugin/pom.xml @@ -18,24 +18,23 @@ Citrus :: Test API Generator :: Maven Plugin Maven Plugin for generation of Citrus Test API + + 2.2.21 + + org.apache.maven.plugins maven-plugin-plugin - 3.10.2 + ${maven.plugin.plugin.version} true - - - 2.2.21 - - @@ -44,75 +43,63 @@ ${project.version} + + commons-io + commons-io + ${commons.io.version} + io.swagger.core.v3 swagger-core ${swagger.version} - io.swagger.core.v3 swagger-models-jakarta ${swagger.version} - - - commons-io - commons-io - 2.16.1 - - org.apache.maven maven-artifact ${maven.version} provided - org.apache.maven maven-core ${maven.version} provided - org.apache.maven maven-plugin-api ${maven.version} provided - org.apache.maven.plugin-tools - maven-plugin-annotations - 3.12.0 + maven-plugin-annotations + ${maven.plugin.annotations.version} provided + org.apache.maven maven-compat ${maven.version} test - org.apache.maven.plugin-testing maven-plugin-testing-harness - 3.3.0 + ${maven.plugin.testing.harness.version} test - - - org.openapitools - openapi-generator-maven-plugin - 7.4.0 - org.assertj assertj-core - 3.25.1 + ${assertj.version} test diff --git a/test-api-generator/pom.xml b/test-api-generator/pom.xml index e015c08518..f6298e3e11 100644 --- a/test-api-generator/pom.xml +++ b/test-api-generator/pom.xml @@ -15,16 +15,15 @@ Citrus Test API Generator pom + + true + + - - org.openapitools - openapi-generator - 7.5.0 - org.junit.jupiter junit-jupiter-engine - 5.10.2 + ${junit.jupiter.version} test