Java Swagger Parser Tutorial

Mohammad Meraj ZiaMarch 25th, 2021Last Updated: May 21st, 2021

0 537 2 minutes read

In Java, a parser is a program or a library that takes in a file (JSON, XML, txt, etc) and converts it to java objects. In this article, we will see how to parse a swagger JSON file.

1. Introduction

It is difficult to write parsers for unstructured data. For example, if you are receiving a text file that has lots of records and there is not much commonality among those records, it is very difficult to write a parser for those. It is easy to build parsers for structured data like Extensible Markup Language (XML) or JavaScript Object Notation (JSON).

2. Java Swagger

Java Swagger allows you to describe your API so that is can be easily read and understood. You can write a Swagger spec for your API manually, or have it generated automatically from annotations in your source code. Swagger definitions can be written in JSON or YAML

3. Code

In this section we will write a code to build a simple RESTful API using Spring boot. We will then add configuration for swagger. Let’s start with the libraries which we will need. For this example, we are going to use maven. We will use the spring-boot-starter-parent as our parent project.

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.4.3</version>
    <relativePath/>
</parent>

Now since this is a web based application we will define a dependency on spring-boot-starter-web.

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

For swagger, we need the below two dependencies:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>

Below is the full code for pom.xml.

pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.4.3</version>
        <relativePath/>
    </parent>

    <groupId>org.javacodegeeks</groupId>
    <artifactId>jcg-swagger-parser</artifactId>
    <version>1.0-SNAPSHOT</version>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>3.0.0</version>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

    <properties>
        <maven.compiler.source>11</maven.compiler.source>
        <maven.compiler.target>11</maven.compiler.target>
    </properties>

</project>

In order for the Java swagger to work, we need to define a config file as below:

package org.javacodegeeks.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SpringFoxConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}

Now let’s run the application by running mvn spring-boot:run. By default, your application will listen to port 8080. Let’s hit the swagger UI URL: http://localhost:8080/swagger-ui/. If everything goes fine you will see the home page for the Swagger UI below

Java Swagger - home page — Figure 1. Swagger home page

4. Summary

In this article, we discussed what is a Parser and how we can use Java Swagger to document our REST-based API service. We looked at the configuration and also how to build a simple REST service using spring boot.