Spring Boot – Swagger2

Swagger2 là 1 project mã nguồn mở được sử dụng để tạo documents REST API cho các dịch vụ web RESTful. Nó cung cấp cho người dùng interface để truy cập dịch vụ web RESTful thông qua browser.

Để bật Swagger2 trong ứng dụng Spring Boot, bạn cần thêm các dependencies sau vào file configurations.

<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.7.0</version>
</dependency>
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.7.0</version>
</dependency>Code language: HTML, XML (xml)

Đối với người sử dụng Gradle, hãy thêm các dependencies sau vào tệp build.gradle.

compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.7.0'
compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.7.0'Code language: JavaScript (javascript)

Bây giờ thêm annotation @EnableSwagger2 vào màn main ứng dụng Spring Boot. Annotation @EnableSwagger2 để đăng ký Swagger2 cho ứng dụng Spring Boot.

Màn main Spring Boot sau khi được thêm annotation:

package com.tutorialspoint.swaggerdemo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
public class SwaggerDemoApplication {
   public static void main(String[] args) {
      SpringApplication.run(SwaggerDemoApplication.class, args);
   }
}Code language: JavaScript (javascript)

Tiếp theo, tạo mới 1 Bean Docket để cấu hình Swagger2 cho ứng dụng Spring Boot. Chúng ta cần định nghĩa base package để cấu hình REST API(s) cho Swagger2.

@Bean
   public Docket productApi() {
      return new Docket(DocumentationType.SWAGGER_2).select()
         .apis(RequestHandlerSelectors.basePackage("com.tutorialspoint.swaggerdemo")).build();
   }Code language: CSS (css)

Bây giờ, inject(tiêm) Bean này vào hàm main Spring Boot, và hàm main sau khi được thêm:

package com.tutorialspoint.swaggerdemo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;

import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
public class SwaggerDemoApplication {
   public static void main(String[] args) {
      SpringApplication.run(SwaggerDemoApplication.class, args);
   }
   @Bean
   public Docket productApi() {
      return new Docket(DocumentationType.SWAGGER_2).select()
         .apis(RequestHandlerSelectors.basePackage("com.tutorialspoint.swaggerdemo")).build();
   }
}Code language: JavaScript (javascript)

Bây giờ, thêm dependency Spring Boot Starter bên dưới vào file configuration để viết REST Endpoints.

Đối với người sử dụng Maven có thể thêm phần dependency vào file pom.xml.

<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-web</artifactId>
</dependency>Code language: HTML, XML (xml)

Đối với người sử dụng Gradle có thể thêm phần dependency vào file build.gradle.

compile('org.springframework.boot:spring-boot-starter-web')Code language: JavaScript (javascript)

Bây giờ, dưới đây là code để xây dụng 2 method RESTful đơn giản GET và POST trong file Rest Controller.

package com.tutorialspoint.swaggerdemo;

import java.util.ArrayList;
import java.util.List;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class SwaggerAPIController {
   @RequestMapping(value = "/products", method = RequestMethod.GET)
   public List<String> getProducts() {
      List<String> productsList = new ArrayList<>();
      productsList.add("Honey");
      productsList.add("Almond");
      return productsList;
   }
   @RequestMapping(value = "/products", method = RequestMethod.POST)
   public String createProduct() {
      return "Product is saved successfully";
   }
}Code language: JavaScript (javascript)

Maven – 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>

   <groupId>com.tutorialspoint</groupId>
   <artifactId>swagger-demo</artifactId>
   <version>0.0.1-SNAPSHOT</version>
   <packaging>jar</packaging>
   <name>swagger-demo</name>
   <description>Demo project for Spring Boot</description>

   <parent>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-parent</artifactId>
      <version>1.5.9.RELEASE</version>
      <relativePath /> <!-- lookup parent from repository -->
   </parent>

   <properties>
      <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
      <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
      <java.version>1.8</java.version>
   </properties>

   <dependencies>
      <dependency>
         <groupId>org.springframework.boot</groupId>
         <artifactId>spring-boot-starter-web</artifactId>
      </dependency>
      
      <dependency>
         <groupId>org.springframework.boot</groupId>
         <artifactId>spring-boot-starter-test</artifactId>
         <scope>test</scope>
      </dependency>
      
      <dependency>
         <groupId>io.springfox</groupId>
         <artifactId>springfox-swagger2</artifactId>
         <version>2.7.0</version>
      </dependency>

      <dependency>
         <groupId>io.springfox</groupId>
         <artifactId>springfox-swagger-ui</artifactId>
         <version>2.7.0</version>
      </dependency>
   </dependencies>

   <build>
      <plugins>
         <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
         </plugin>
      </plugins>
   </build>
   
</project>Code language: HTML, XML (xml)

Gradle – build.gradle

buildscript {
   ext {
      springBootVersion = '1.5.9.RELEASE'
   }
   repositories {
      mavenCentral()
   }
   dependencies {
      classpath("org.springframework.boot:spring-boot-gradle-plugin:${springBootVersion}")
   }
}
apply plugin: 'java'
apply plugin: 'eclipse'
apply plugin: 'org.springframework.boot'

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

repositories {
   mavenCentral()
} dependencies {
   compile('org.springframework.boot:spring-boot-starter-web')
   testCompile('org.springframework.boot:spring-boot-starter-test')
   compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.7.0'
   compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.7.0'
}Code language: JavaScript (javascript)

Bạn có thể tạo file JAR và run ứng dụng Spring Boot bằng cách dùng các lệnh Maven hoặc Gradle sau.

Đối với Maven:

mvn clean install

Sau khi “BUILD SUCCESS” thì bạn có thể tìm thấy file JAR trong thư mục đích.

Còn đối với Gradle:

gradle clean build

Sau khi “BUILD SUCCESS” thì bạn có thể tìm thấy file JAR trong thư mục build/libs.

Bây giờ, chạy file JAR sử dụng lệnh sau:

java –jar <JARFILE> Code language: HTML, XML (xml)

Ứng dụng sẽ khởi động trên cổng Tomcat 8080 như hình dưới:

Cuối cùng, truy cập http://localhost:8080/swagger-ui.html để xem các chức năng của Swagger API nhé.

Chúc bạn thành công.

Bài viết được tham khảo từ nguồn:

https://www.tutorialspoint.com/spring_boot/spring_boot_enabling_swagger2.htm