Spring boot Swagger Integration

- March 01, 2019

Benefits of swagger UI

Demonstrating SwaggerUI integration with springBoot without using springfox java annotations.

There are many articles over the internet that gives you swagger integration with spring boot using springfox annotations into the code.

Following major concerns with that approach:

Your controller code polluted with springfox java annotations.
You wont find proper request and response payload descriptions (what attributes is mandatory etc)
Tightly coupled with your business logic with API documentation
API documentation dependencies will goes into final artifact which increases the size
Not possible to customize Swagger UI as per your organization needs

Benefits of swagger UI

✓ You will have clean separation of API documentation with your business logic (in controller layer/ request payloads)
✓ You will have full control of API documentation to define your endpoints with attribute level description.
✓ No third-party jars/ annotations (spring-fox) required.
✓ Easy to enabled security (OAuth) and basic input payload validations without any annotations)
✓ Rich UI for API documentation ( You can customized UI using swagger-ui source code project)

Steps to Integrate

Create spring-boot gradle project

build.gradle

plugins {
 id 'org.springframework.boot' version '2.1.3.RELEASE'
 id 'java'
}

apply plugin: 'io.spring.dependency-management'

group = 'com.tvajjala'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '1.8'

repositories {
 mavenCentral()
}

dependencies {
 implementation 'org.springframework.boot:spring-boot-starter-web'
 testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

Create your API Definitions

Create API definitions at https://editor.swagger.io/ and save it as swagger-api.yaml under resource folder of your project.

swagger-api.yaml

openapi: 3.0.1
tags:
- name: user
  description: Operations about user
  externalDocs:
    description: Find out more blogs at
    url: https://tvajjala.in
paths:
  /user:
    post:
      tags:
      - user

....
(1)

Refer github repo for complete yaml document.

Write simple html file and refer API definitions

swagger-ui.html

<!-- HTML for static distribution bundle build -->
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Swagger UI</title>
    <link rel="stylesheet" type="text/css"
          href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.28.0/swagger-ui.min.css"> (1)
</head>

<body>
<div id="swagger-ui"></div>

<script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.28.0/swagger-ui-bundle.min.js"></script> (2)
<script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.28.0/swagger-ui-standalone-preset.min.js"></script> (3)
<script>
    window.onload = function() {
      // Begin Swagger UI call region
      const ui = SwaggerUIBundle({
        url: "/api/swagger.yaml", //(4)
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        plugins: [
          SwaggerUIBundle.plugins.DownloadUrl
        ],
        layout: "StandaloneLayout"
      })
      // End Swagger UI call region

      window.ui = ui
    }

</script>
</body>
</html>

Swagger UI CDN links for CSS
Swagger UI CDN javascript
Swagger UI CDN javascript
Refer Your swagger definition (.yaml) file

Write Swagger Configuration file

SwaggerConfig.java

package com.tvajjala.swagger.config;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.ViewControllerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

/**
 * Swagger UI project configuration to render, clean API documentation without using springfox annotations
 *
 * @author ThirupathiReddy Vajjala
 */

@Configuration
public class SwaggerConfig implements WebMvcConfigurer {


    private static final Logger LOGGER = LoggerFactory.getLogger(SwaggerConfig.class);


    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        LOGGER.info("Adding resource handlers to the swagger UI");
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/static/swagger-ui.html");
        registry.addResourceHandler("api/**").addResourceLocations("classpath:/api-doc/");
    }


    @Override
    public void addCorsMappings(CorsRegistry registry) {
        LOGGER.info("Enabling Cross Origin Resource Sharing  ");
        registry.addMapping("/*");// all the end-points now can be accessible from other domains
    }

    @Override
    public void addViewControllers(ViewControllerRegistry registry) {
        registry.addRedirectViewController("/", "swagger-ui.html");
    }

}

Start the server http://localhost:8080/swagger-ui.html which renders beautiful swagger ui

source code

Refer complete codebase for quick setup at https://github.com/tvajjala/spring-boot-swagger-ui

Search This Blog

https://codergists.blogspot.com