[Spring boot + Rest API] Swagger

1. Swagger! Why?

Hiểu nôm na thế này, swagger là một công cụ chô phép bạn đặc tả các rest api của mình để người các người dùng khác có thể đọc, hiểu và sử dụng. Công cụ này hỗ trợ những thứ gì - nhiều lắm. Chi tiết các bạn có thể đọc tại page của nó. https://swagger.io/docs/specification/2-0/what-is-swagger/ Swgger support các annotation giúp ứng dụng spring có thể mô tả các restapi, đồng thời tự động build một giao diện trực quan giúp người dùng tương tác trực tiếp với các rest api đó.

2. How

Swagger đọc cái thông tin về rest api và tự động tạo ra một file json. Sau đó đọc dữ liệu từ các json đấy để build lên cấu trúc của cái giao diện trực quan kia

3. Ví dụ cụ thể

Trong bài viếu đầu tiên trong loạt bài về restapi + springboot. Link tại đây: https://viblo.asia/p/spring-boot-rest-api-overview-6J3ZgObAZmB M có đề cập đến một cách viết restapi sử dụng Jersey. Trong bài viết này, m đề cấp tới cách tích hợp swagger với các restapi viết theo cách này. Bạn hoàn toàn có thể dùng swagger để tích hợp tích hợp với restapi viết theo các cách còn lại.

1. Maven Dependency

  <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-jersey2-jaxrs</artifactId>
            <version>1.5.8</version>
        </dependency>

2. Tạo một resourceconfig

 public MyResourceConfig() {
        registerEndpoints();
    }

    private void registerEndpoints() {
        register(CarEndpoint.class);  // dang ki cai endpoint nay
        configureSwagger();
    }

    private void configureSwagger() {
        this.register(ApiListingResource.class);   // build file json mo ta cau truc cac restapi
        this.register(SwaggerSerializers.class);   // tao ra mot object swagger tu cai file json

        BeanConfig config = new BeanConfig();  // khoi tao mot bean config cho swagger
        config.setConfigId("my-jersey");
        config.setTitle("Rest API");
        config.setDescription("Demo rest api");
        config.setVersion("v1");
        config.setBasePath("/api");
        config.setResourcePackage("com.vnpt.ssdc"); 
        config.setPrettyPrint(true);
        config.setScan(true);
        
    }

3. Tạo endpoint

@Path("/car")
@Api("Car Endpoint")
public class CarEndpoint {

    class Info implements Serializable {

        public String username;
        public String password;

        public Info(String username, String password) {
            this.username = username;
            this.password = password;
        }

    }

    @GET
    public Info getAll() {
        return new Info("soithattha", "password");
    }

}

4. Tích hợp source của swagger

1. Các bạn download cái swagger-ui từ link này :https://github.com/swagger-api/swagger-ui/tree/master/dist
2. Đặt trong thư mục resource/static/api-document trong cấu trúc thư mục của ứng dụng
3. Mặc định nó đang đọc dữ liệu từ file json url: "https://petstore.swagger.io/v2/swagger.json". Sửa lại link trong file index.html -> url: "http://localhost:8088/api/swagger.json".

5. Demo

Sau đó run project và truy cập link http://localhost:8088/api-document/index.html là sẽ thấy điều kì diệu

6. Link project

https://github.com/soithattha/spring-rest-api.git