Swagger là gì? Tạo document cho API RESTful Web Service

Swagger là gì? Tạo document cho API RESTful Web Service

Swagger là gì?

Swagger là một phần mềm mã nguồn mở được sử dụng để phát triển, thiết kế, xây dựng và làm tài liệu cho các RESTful Web Service.

Có một số phần mềm Swagger như Swagger Editor, Swagger Codegen, Swagger Inspector, Swagger UI.

Trong đó, Swagger UI được sử dụng nhiều nhất, nó hỗ trợ tự động làm tài liệu, sinh code và sinh test case.

Ví dụ Swagger UI

Để dễ hiểu, các bạn có thể truy cập đường link http://petstore.swagger.io/ để demo với Swagger UI

Ta có thể biết rõ được có những API nào, method và url tương ứng của nó

Swagger là gì? Tạo document cho API RESTful Web Service

Với mỗi api ta lại biết được chi tiết input và output của như trường nào bắt buộc gửi lên, kết quả trả về có thể nhận những status nào…

Swagger là gì? Tạo document cho API RESTful Web Service Swagger là gì? Tạo document cho API RESTful Web Service

Bạn cũng có thể dễ dàng trình bày các api trong project của mình như trên với Swagger UI.

Giả sử bạn là đứa code backend, sau khi code xong các api, Swagger UI sẽ tự động trình bày các API để đứa code front end biết được api này hoạt động như nào và có thể thực hiện test luôn trên Swagger với api đó.

Cài đặt Swagger UI.

Swagger UI là phần mềm mã nguồn mở, bạn có thể download nó tại github https://github.com/swagger-api/swagger-ui

download swagger ui

Sau khi tải được file zip, bạn giải nén ra một folder, trong folder đó sẽ có thư dist, đây chính là bản Swagger UI mà ta sẽ sử dụng.

Bạn có thể copy folder dist và deploy nó lên một server hoặc mở file index.html trên trình duyệt để chạy Swagger UI.

Ở đây mình mở luôn file index.html trên trình duyệt.

cài đặt swagger ui

Kết quả:

demo swagger ui

Trong ô explore chính là đường linh tới nội dung đặc tả các api. Các bạn có thể thử với http://petstore.swagger.io/v2/swagger.json

Ở bài tiếp theo mình sẽ thực hiện tạo nội dung đặc tả cho api từ code có sẵn để hiện lên Swagger UI với project Spring Boot RESTful api

Swagger là gì? Tạo document cho API RESTful Web Service stackjava.com

Okay, Done!

References:

swagger.io/docs/specification/about

stackjava.com