| Branch | Build Status |
|---|---|
| master |
This repository contains modules related to the server related REST apis. It can be compiled using JDK 8, JDK 11 or JDK 17.
To generate stub, the swagger2cxf-maven-plugin is used.
We have done improvements to this plugin so that the stubs can be generated within a given package name. Therefore you can define multiple swagger files and deploy them in a single web application. To get the improvements locally, please follow the given steps.
- Clone the repository https://github.com/madurangasiriwardena/openapi-generator-cxf-wso2
git clone https://github.com/madurangasiriwardena/openapi-generator-cxf-wso2
- Build the plugin (master branch)
mvn clean install
Now, the locally built openapi-generator-cxf plugin will be picked from the local .m2 repository when generating the stubs.
In this repository each server resource type is represented by a unique component. Hence, you need to create a new maven module for the resource type. Under this component the implementation of each major version will have a unique component along with version in it's name.
- Include the API swagger definition (in OpenAPI 3.0) in the given location of this maven project (identity-api-server).
The suggested name for the file name of the API definition is
<resource>.yaml.
If you are working with Swagger 2.0 still, you have to convert the API definition to OpenAPI 3.0
+-- identity-api-server
| +-- components
| +-- org.wso2.carbon.identity.api.server.<resource>
| +-- org.wso2.carbon.identity.api.server.<resource>.<version>
| +-- src
| +-- main
| +-- resources
| +--api.yaml
| +-- pom.xml
| +-- pom.xml
Let's consider sample definition as challenge.yaml
+-- identity-api-server
| +-- components
| +-- org.wso2.carbon.identity.api.server.challenge
| +-- org.wso2.carbon.identity.api.server.challenge.v1
| +-- src
| +-- main
| +-- resources
| +--challenge.yaml
| +-- pom.xml
| +-- pom.xml
- Include the given plugin to the
pom.xmlfile of the moduleorg.wso2.carbon.identity.api.server.<resource> .<version>
<plugin>
<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<version>4.1.2</version>
<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<inputSpec>${project.basedir}/src/main/resources/<resource>.yaml</inputSpec>
<generatorName>org.wso2.carbon.codegen.CxfWso2Generator</generatorName>
<configOptions>
<sourceFolder>src/gen/java</sourceFolder>
<apiPackage>org.wso2.carbon.identity.api.server.<resource>.<version></apiPackage>
<modelPackage>org.wso2.carbon.identity.api.server.<resource>.<version>.model</modelPackage>
<packageName>org.wso2.carbon.identity.api.server.<resource>.<version></packageName>
<dateLibrary>java8</dateLibrary>
<hideGenerationTimestamp>true</hideGenerationTimestamp>
</configOptions>
<output>.</output>
<skipOverwrite>false</skipOverwrite>
</configuration>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>org.openapitools</groupId>
<artifactId>cxf-wso2-openapi-generator</artifactId>
<version>1.0.0</version>
</dependency>
</dependencies>
</plugin>
For our example:
<plugin>
<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<version>4.1.2</version>
<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<inputSpec>${project.basedir}/src/main/resources/challenge.yaml</inputSpec>
<generatorName>org.wso2.carbon.codegen.CxfWso2Generator</generatorName>
<configOptions>
<sourceFolder>src/gen/java</sourceFolder>
<apiPackage>org.wso2.carbon.identity.api.server.challenge.v1</apiPackage>
<modelPackage>org.wso2.carbon.identity.api.server.challenge.v1.model</modelPackage>
<packageName>org.wso2.carbon.identity.api.server.challenge.v1</packageName>
<dateLibrary>java8</dateLibrary>
<hideGenerationTimestamp>true</hideGenerationTimestamp>
</configOptions>
<output>.</output>
<skipOverwrite>false</skipOverwrite>
</configuration>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>org.openapitools</groupId>
<artifactId>cxf-wso2-openapi-generator</artifactId>
<version>1.0.0</version>
</dependency>
</dependencies>
</plugin>
- Do a maven build inside the module
org.wso2.carbon.identity.api.server.<resource>.<version>to generate the stubsmvn clean install - Comment out the plugin added for your API definition before committing to the git. Because it will regenerate during each build.
A new version is introduced only when a major version of API swagger definition is introduced.
- Locate the correct parent module of the current API implementation. Create a new module with the new version and include the API swagger definition in the new module project . Suggested name for the file name of the API definition is .yaml
+-- identity-api-server
| +-- components
| +-- org.wso2.carbon.identity.api.server.<resource>
| +-- org.wso2.carbon.identity.api.server.<resource>.<version>
| +-- src
| +-- main
| +-- resources
| +--api.yaml
| +-- pom.xml
| +-- org.wso2.carbon.identity.api.server.<resource>.<version+1>
| +-- src
| +-- main
| +-- resources
| +--api.yaml
| +-- pom.xml
| +-- pom.xml
Let's consider sample definition as challenge.yaml
+-- identity-api-server
| +-- components
| +-- org.wso2.carbon.identity.api.server.challenge
| +-- org.wso2.carbon.identity.api.server.challenge.v1
| +-- src
| +-- main
| +-- resources
| +--challenge.yaml
| +-- pom.xml
| +-- org.wso2.carbon.identity.api.server.challenge.v2
| +-- src
| +-- main
| +-- resources
| +--challenge.yaml
| +-- pom.xml
| +-- pom.xml
- Include the given plugin to the
pom.xmlfile of the moduleorg.wso2.carbon.identity.api.server.<resource>.<version+1>
<plugin>
<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<version>4.1.2</version>
<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<inputSpec>${project.basedir}/src/main/resources/<resource>.yaml</inputSpec>
<generatorName>org.wso2.carbon.codegen.CxfWso2Generator</generatorName>
<configOptions>
<sourceFolder>src/gen/java</sourceFolder>
<apiPackage>org.wso2.carbon.identity.api.server.<resource>.<version+1></apiPackage>
<modelPackage>org.wso2.carbon.identity.api.server.<resource>.<version+1>.model</modelPackage>
<packageName>org.wso2.carbon.identity.api.server.<resource>.<version+1></packageName>
<dateLibrary>java8</dateLibrary>
<hideGenerationTimestamp>true</hideGenerationTimestamp>
</configOptions>
<output>.</output>
<skipOverwrite>false</skipOverwrite>
</configuration>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>org.openapitools</groupId>
<artifactId>cxf-wso2-openapi-generator</artifactId>
<version>1.0.0</version>
</dependency>
</dependencies>
</plugin>
For our example:
<plugin>
<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<version>4.1.2</version>
<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<inputSpec>${project.basedir}/src/main/resources/challenge.yaml</inputSpec>
<generatorName>org.wso2.carbon.codegen.CxfWso2Generator</generatorName>
<configOptions>
<sourceFolder>src/gen/java</sourceFolder>
<apiPackage>org.wso2.carbon.identity.api.server.challenge.v2</apiPackage>
<modelPackage>org.wso2.carbon.identity.api.server.challenge.v2.model</modelPackage>
<packageName>org.wso2.carbon.identity.api.server.challenge.v2</packageName>
<dateLibrary>java8</dateLibrary>
<hideGenerationTimestamp>true</hideGenerationTimestamp>
</configOptions>
<output>.</output>
<skipOverwrite>false</skipOverwrite>
</configuration>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>org.openapitools</groupId>
<artifactId>cxf-wso2-openapi-generator</artifactId>
<version>1.0.0</version>
</dependency>
</dependencies>
</plugin>
- Do a maven build inside the module
org.wso2.carbon.identity.api.server.<resource>.<version+1>to generate the stubsmvn clean install - Comment out the plugin added for your API definition before committing to the git.
Once you execute the above steps to generate the code it will generate set of java classes defining the Basic API definition.
├── src
│ ├── gen
│ │ └── java.org.wso2.carbon.identity.rest.api.server.<resource>.<version>
│ └── main
│ ├── java
│ │ └── java.org.wso2.carbon.identity.rest.api.server.<resource>.<version>.impl
In our example
├── src
│ ├── gen
│ │ └── java.org.wso2.carbon.identity.rest.api.server.challenge.v1
│ └── main
│ ├── java
│ │ └── java.org.wso2.carbon.identity.rest.api.server.challenge.v1.impl
You need to implement the functions of the classes under java.org.wso2.carbon.identity.rest.api.server.challenge.v1 .impl package to respond with desired output.
Inorder to improve re-usability of common implementations between versions, we encourage you to include a common
component org.wso2.carbon.identity.api.server.<resource>.common for your resource type component as below.
+-- identity-api-server
| +-- components
| +-- org.wso2.carbon.identity.api.server.<resource>
| +-- org.wso2.carbon.identity.api.server.<resource>.common
| +-- src
| +-- pom.xml
| +-- org.wso2.carbon.identity.api.server.<resource>.<version>
| +-- src
| +-- main
| +-- resources
| +--api.yaml
| +-- pom.xml
| +-- org.wso2.carbon.identity.api.server.<resource>.<version+1>
| +-- src
| +-- main
| +-- resources
| +--api.yaml
| +-- pom.xml
| +-- pom.xml
Let's consider sample resource
+-- identity-api-server
| +-- components
| +-- org.wso2.carbon.identity.api.server.challenge
| +-- org.wso2.carbon.identity.api.server.challenge.common
| +-- src
| +-- pom.xml
| +-- org.wso2.carbon.identity.api.server.challenge.v1
| +-- src
| +-- main
| +-- resources
| +--challenge.yaml
| +-- pom.xml
| +-- org.wso2.carbon.identity.api.server.challenge.v2
| +-- src
| +-- main
| +-- resources
| +--challenge.yaml
| +-- pom.xml
| +-- pom.xml
You may add this common component in both the api version specific components as dependency and reuse.
To integrate the API implemented in identity-api-server in a single web app , follow the steps in https://github.com/wso2/identity-rest-dispatcher/blob/master/README.md