Home » Core Java » Java Swagger Parser Tutorial

About Mohammad Meraj Zia

Senior Java Developer

Java Swagger Parser Tutorial

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.

5. Download source code

Download
You can download the full source code of this example here: Java Swagger Parser Tutorial

Do you want to know how to develop your skillset to become a Java Rockstar?

Subscribe to our newsletter to start Rocking right now!

To get you started we give you our best selling eBooks for FREE!

 

1. JPA Mini Book

2. JVM Troubleshooting Guide

3. JUnit Tutorial for Unit Testing

4. Java Annotations Tutorial

5. Java Interview Questions

6. Spring Interview Questions

7. Android UI Design

 

and many more ....

 

Receive Java & Developer job alerts in your Area

 

Subscribe
Notify of
guest

This site uses Akismet to reduce spam. Learn how your comment data is processed.

0 Comments
Inline Feedbacks
View all comments