Generating Swagger files for JAX-RS source code

I wanted to generate the swagger files for few Rest APIs used in WSO2 Open Banking and as this is the first time I’m generating swagger for source code or vice versa I thought I’ll share this experience with you guys.

In this post, I will share how I integrated the swagger-maven-plugin plugin to generate swagger yamls for JAX-RS code.

A Swagger file or a swagger specification defines a set of files that will work together to form a RestAPI. You can use the https://editor.swagger.io/ swagger editor to design, define and document the RestAPIs.

So, this is how to generate the swagger files:

• Navigate to the module where you have the JAX-RS files you want to generate the swagger for. Go to the module’s pom file and add the following configs under the <plugins> property.

• You have to make sure the package in the <location> property, contains the source code you want these swagger file to define.
• The output would be a yaml file which will be generated in the generated/swagger-ui directory as stet-payments140.yaml. All these were configured using the above configurations.
• Configure the properties below as these are mandatory for this tool to generate the file.

<info>    
    <title>PaymentConsentAPI</title>                             
    <version>1.4.0</version>
</info>
<swaggerDirectory>generated/swagger-ui</swaggerDirectory>

• If you do not define the <swaggerDirectory>, the swagger won’t get generated.
• If <swaggerFileName> is not configured, it will give the output in a file called swagger.json.
• And the java classes should have the io.swagger.annotations.Api (@Api) annotation. In my source code, I had it defined in this manner

@io.swagger.annotations.Api(value = “/payment-requests”, description = “the payment-requests API”)

• Now open a terminal from the location where you have the pom file and issue this command.

mvn compile

• If the compilation is successful you will have the stet-payments140.yaml in the generated/swagger-ui directory.
• Use the https://editor.swagger.io/# editor and validate the swagger

Well, now you can enjoy your swagger :D!