Skip to main content
Hashnodedevngu

Command Palette

Search for a command to run...

Bài 15: Spring Boot và Swagger

Published
•6 min read•View as Markdown
D
devngu

1. Giới thiệu về Swagger

Swagger là một công cụ mạnh mẽ để tạo tài liệu và kiểm thử các API RESTful. Nó cung cấp một giao diện người dùng trực quan để khám phá và tương tác với các API một cách dễ dàng. Swagger giúp cải thiện trải nghiệm của các nhà phát triển khi làm việc với các API bằng cách cung cấp một cách tiếp cận có cấu trúc và tiêu chuẩn hóa.

2. Cách tích hợp Swagger vào dự án Spring Boot

2.1. Thêm dependency

Đầu tiên, bạn cần thêm các dependency cần thiết vào dự án của mình. Hiện nay, Springfox là một thư viện phổ biến để tích hợp Swagger vào Spring Boot.

Ví dụ với Maven:

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

Ví dụ với Gradle:

implementation 'io.springfox:springfox-boot-starter:3.0.0'

2.2. Cấu hình Swagger

Bạn cần tạo một lớp cấu hình để thiết lập Swagger trong ứng dụng Spring Boot.

Ví dụ:

// SwaggerConfig.java
package com.example.myapp.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.myapp.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("My Spring Boot REST API")
                .description("REST API documentation for my Spring Boot application")
                .version("1.0.0")
                .build();
    }
}

2.3. Sử dụng các annotation của Swagger

Swagger cung cấp một số annotation để mô tả API của bạn một cách rõ ràng và chi tiết hơn. Các annotation này bao gồm @Api, @ApiOperation, @ApiParam, @ApiModel, @ApiModelProperty, và nhiều annotation khác.

Ví dụ:

// UserController.java
package com.example.myapp.controller;

import com.example.myapp.entity.User;
import com.example.myapp.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping("/api/users")
@Api(value = "User Management System", description = "Operations pertaining to user in User Management System")
public class UserController {

    @Autowired
    private UserService userService;

    @ApiOperation(value = "View a list of available users", response = List.class)
    @GetMapping
    public List<User> getAllUsers() {
        return userService.findAll();
    }

    @ApiOperation(value = "Get a user by Id")
    @GetMapping("/{id}")
    public ResponseEntity<User> getUserById(@ApiParam(value = "ID of the user to be retrieved", required = true) @PathVariable Long id) {
        User user = userService.findById(id);
        if (user != null) {
            return ResponseEntity.ok(user);
        } else {
            return ResponseEntity.notFound().build();
        }
    }

    @ApiOperation(value = "Create a new user")
    @PostMapping
    public User createUser(@ApiParam(value = "User object to be created", required = true) @RequestBody User user) {
        return userService.save(user);
    }

    @ApiOperation(value = "Update an existing user")
    @PutMapping("/{id}")
    public ResponseEntity<User> updateUser(@ApiParam(value = "ID of the user to be updated", required = true) @PathVariable Long id,
                                           @ApiParam(value = "Updated user object", required = true) @RequestBody User userDetails) {
        User user = userService.findById(id);
        if (user != null) {
            user.setName(userDetails.getName());
            user.setEmail(userDetails.getEmail());
            return ResponseEntity.ok(userService.save(user));
        } else {
            return ResponseEntity.notFound().build();
        }
    }

    @ApiOperation(value = "Delete a user")
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteUser(@ApiParam(value = "ID of the user to be deleted", required = true) @PathVariable Long id) {
        userService.deleteById(id);
        return ResponseEntity.noContent().build();
    }
}

2.4. Truy cập giao diện Swagger UI

Sau khi cấu hình xong, bạn có thể truy cập giao diện Swagger UI tại URL http://localhost:8080/swagger-ui.html để xem và tương tác với tài liệu API của bạn.

3. Ví dụ chi tiết

Dưới đây là một ví dụ chi tiết từ đầu đến cuối về việc tích hợp Swagger vào một ứng dụng Spring Boot RESTful.

3.1. Tạo dự án Spring Boot

Sử dụng Spring Initializr để tạo dự án với các dependency sau:

  • Spring Web

  • Spring Data JPA

  • H2 Database (hoặc MySQL nếu bạn muốn)

  • Springfox Swagger

3.2. Cấu hình application.properties

# application.properties
spring.datasource.url=jdbc:h2:mem:testdb
spring.datasource.driverClassName=org.h2.Driver
spring.datasource.username=sa
spring.datasource.password=password
spring.jpa.database-platform=org.hibernate.dialect.H2Dialect
spring.h2.console.enabled=true
spring.jpa.hibernate.ddl-auto=update

3.3. Tạo Entity User

// User.java
package com.example.myapp.entity;

import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;

@Entity
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String name;
    private String email;

    // getters and setters
}

3.4. Tạo Repository UserRepository

// UserRepository.java
package com.example.myapp.repository;

import com.example.myapp.entity.User;
import org.springframework.data.jpa.repository.JpaRepository;

public interface UserRepository extends JpaRepository<User, Long> {
}

3.5. Tạo Service UserService

// UserService.java
package com.example.myapp.service;

import com.example.myapp.entity.User;
import com.example.myapp.repository.UserRepository;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.List;

@Service
public class UserService {
    @Autowired
    private UserRepository userRepository;

    public List<User> findAll() {
        return userRepository.findAll();
    }

    public User findById(Long id) {
        return userRepository.findById(id).orElse(null);
    }

    public User save(User user) {
        return userRepository.save(user);
    }

    public void deleteById(Long id) {
        userRepository.deleteById(id);
    }
}

3.6. Tạo Controller UserController

// UserController.java
package com.example.myapp.controller;

import com.example.myapp.entity.User;
import com.example.myapp.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping("/api/users")
@Api(value = "User Management System", description = "Operations pertaining to user in User Management System")
public class UserController {

    @Autowired
    private UserService userService;

    @ApiOperation(value = "View a list of available users", response = List.class)
    @GetMapping
    public List<User> getAllUsers() {
        return userService.findAll();
    }

    @ApiOperation(value = "Get a user by Id")
    @GetMapping("/{id}")
    public ResponseEntity<User> getUserById(@ApiParam(value = "ID of the user to be retrieved", required = true) @PathVariable Long id) {
        User user = userService.findById(id);
        if (user != null) {
            return ResponseEntity.ok(user);
        } else {
            return ResponseEntity.notFound().build();
        }
    }

    @ApiOperation(value = "Create a new user")
    @PostMapping
    public User createUser(@ApiParam(value = "User object to be created", required = true) @RequestBody User user) {
        return userService.save(user);
    }

    @ApiOperation(value = "Update an existing user")
    @PutMapping("/{id}")
    public ResponseEntity<User> updateUser(@ApiParam(value = "ID of the user to be updated", required = true) @PathVariable Long id,
                                           @ApiParam(value

 = "Updated user object", required = true) @RequestBody User userDetails) {
        User user = userService.findById(id);
        if (user != null) {
            user.setName(userDetails.getName());
            user.setEmail(userDetails.getEmail());
            return ResponseEntity.ok(userService.save(user));
        } else {
            return ResponseEntity.notFound().build();
        }
    }

    @ApiOperation(value = "Delete a user")
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteUser(@ApiParam(value = "ID of the user to be deleted", required = true) @PathVariable Long id) {
        userService.deleteById(id);
        return ResponseEntity.noContent().build();
    }
}

3.7. Cấu hình Swagger

// SwaggerConfig.java
package com.example.myapp.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.myapp.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("My Spring Boot REST API")
                .description("REST API documentation for my Spring Boot application")
                .version("1.0.0")
                .build();
    }
}

3.8. Chạy ứng dụng

Chạy ứng dụng bằng cách sử dụng Maven:

mvn spring-boot:run

Truy cập giao diện Swagger UI tại URL http://localhost:8080/swagger-ui.html để xem và tương tác với tài liệu API của bạn.

4. Kết luận

Trong bài viết này, chúng ta đã tìm hiểu về cách tích hợp Swagger vào dự án Spring Boot để tạo tài liệu API tự động. Swagger cung cấp một giao diện người dùng trực quan để khám phá và tương tác với các API một cách dễ dàng, giúp cải thiện trải nghiệm của các nhà phát triển khi làm việc với các API.

Trong bài viết tiếp theo, chúng ta sẽ tìm hiểu về cách tích hợp Thymeleaf vào dự án Spring Boot để tạo giao diện web động.

#muaxuan

Comments

Join the discussion

No comments yet. Be the first to comment.

More from this blog

devngu

169 posts