Tài liệu Golang RESTful API với Swagger

Tram Ho

Bắt đầu

Việc xây dựng một API không được hoàn thành nếu không có tài liệu có ý nghĩa về các API của chúng tôi cũng như khả năng kiểm tra các điểm cuối của nó, người dùng thậm chí sẽ không cố gắng sử dụng nó. Giải pháp cho điều đó là viết tài liệu. Tuy nhiên, viết nó có thể mất nhiều thời gian. May mắn thay, có một công cụ có sẵn để giúp chúng tôi và đó là Swagger.

Vênh vang trong cờ vây

Hãy bắt đầu với các thư viện cần thiết để tạo tài liệu Swagger. Có nhiều gói chúng ta có thể sử dụng nhưng hai lựa chọn phổ biến là go-swaggerswag . go-swageer dường như là một lựa chọn phổ biến giữa hai người, nhưng cấu hình và đường cong học tập hơi phức tạp nên trong bài này chúng ta sẽ đi với swag .

swag cho phép sử dụng tạo tài liệu vênh vang từ nhận xét tài liệu ( godoc ) và nó rất đơn giản để sử dụng. Tất cả những gì chúng ta cần làm là ghi lại chức năng xử lý của chúng ta khi chúng ta viết mã và sử dụng công cụ dòng lệnh thì chúng ta sẽ làm tốt. Tôi chỉ cho bạn cách tạo tài liệu vênh vang bằng cách xây dựng ứng dụng Todo. Dự án ví dụ có thể được tìm thấy trong kho github của tôi, hãy chắc chắn kiểm tra xem.

Bootstraping

Để bắt đầu, trước tiên chúng ta cần cài đặt công cụ dòng lệnh mà chúng ta cần bằng cách chạy

Sau đó cd vào một dự án gốc và sau đó chạy swag init . Lệnh này sẽ hy vọng rằng có một tệp có tên main.go trong thư mục hiện tại, nhưng trong ví dụ của chúng tôi, mục nhập là cmd/server/main.go vì vậy chúng ta cần truyền cờ -g như thế này

Điều này sẽ tạo ra một thư mục docs mới trong dự án gốc. Trước khi chúng tôi mô tả các điểm cuối API riêng lẻ, trước tiên chúng tôi cần viết mô tả chung cho toàn bộ dự án của chúng tôi. Phần chú thích này nằm trong gói chính của bạn, ngay trước chức năng chính

Điều này sẽ xác định Thông tin API chung, bao gồm những thứ như tên, phiên bản, URL cơ sở, v.v. Có một vài trường nữa mà bạn có thể bao gồm và chúng được liệt kê trong trang github swag .

Ngoài các chú thích, chúng tôi cũng cần nhập các thư viện cần thiết bao gồm nhập trống gói tài liệu mà chúng tôi đã tạo. Một điều nữa chúng ta cần làm là thực sự gắn kết Swagger UI ở một số điểm cuối, ở đây chúng ta sử dụng /swagger/* . Ở đây tôi sử dụng echo nhưng bạn có thể sử dụng swag với khá nhiều khung công tác bạn muốn.

Hoạt động

Để có được danh sách hoạt động hiển thị trong UI của chúng ta, chúng ta cần chú thích và xử lý chức năng. Các chú thích này đứng trước mỗi hàm xử lý mà chúng ta gắn kết như là điểm cuối API của chúng tôi và trong trường hợp này là todo.FindTodos , todo.CreateTodo , todo.GetTodo , todo.UpdateTodo , todo.DeleteTodo . Nó trông như thế nào

Gần như tất cả những điều này là tự giải thích, vì vậy tôi sẽ bỏ qua một vài trong số chúng và chỉ chỉ ra một trong những điều quan trọng.

  • @Param : mô tả tải trọng yêu cầu của chúng tôi, nó phải ở dạng {name} {type} {dataType} {required} {comment} phân tách bằng dấu cách, do đó, trong trường hợp này, nó được dịch sang tên param todo trong thân yêu cầu với trường như được định nghĩa trong type.Todo struct, nó là bắt buộc và với mô tả New Todo.
  • @Success : phải ở dạng {status} {returnType} {dataType} {comment} và trong trường hợp của chúng tôi, nó sẽ trả về 200 mã trạng thái với type.Todo làm đối tượng phản hồi khi cuộc gọi api thành công.
  • @Failure : giống như @Success nhưng đối với trường hợp khi cuộc gọi api không thành công.
  • @Router : ở dạng {path} [method] .

Và đây là tất cả những gì chúng ta cần để mô tả một điểm cuối duy nhất bây giờ tất cả những gì còn lại để cập nhật tài liệu của chúng tôi với những thay đổi mới này bằng cách gọi lại swag init -g cmd/server/main.go Nếu mọi thứ đều ổn thì chúng ta có thể khởi động máy chủ của mình bằng cách go run github.com/PrinceNorin/cmd/server sau đó điều hướng đến http://localhost:8081/swagger/index.html sau đó bạn sẽ thấy một cái gì đó như thế này

Chia sẻ bài viết ngay

Nguồn bài viết : Viblo