Xây dựng ứng dụng web tạo tài liệu api có kèm mock api với swagger-node
White

Kong Minh viết ngày 14/10/2019

1. Mục tiêu đối với ứng dụng:

  • Tạo và cập nhật được nội dung các api (api editor).
  • Share được tài liệu api cho team member (api docs).
  • Có mock api giúp developer và tester được trực quan và dễ dàng khi sử dụng api, developer có thể sử dụng tạm mock api luôn nếu api thật chưa có sẵn.

2. Cài đặt môi trường và ứng dụng:

  • Cài đặt node và npm.
  • Cài đặt node swagger:

$ npm install -g swagger

  • Tạo ứng dụng:

$ swagger project create hello-api

  • Edit api: vào thư mục ứng dụng hello-api và chạy lệnh

$ swagger project edit

sẽ bật lên cửa sổ trình duyệt để bạn sửa api.

  • Xem tài liệu api:

$ swagger project start

truy cập vào đường dẫn api docs để view tài liệu: http://127.0.0.1:10010/docs/
Nhưng bạn sẽ không thấy hiện ra tài liệu api mà thấy báo lỗi:

Cannot GET /docs/

Mở file hello-api/app.js và thêm vào bên dưới dòng if (err) { throw err; } đoạn code sau:

app.use(swaggerExpress.runner.swaggerTools.swaggerUi());

Truy cập lại link trên sẽ thấy hiển thị tài liệu api rất đẹp mắt và dễ sử dụng.
Trong tài liệu này bạn có thể gọi trực tiếp mock api và xem được response trả về, api docs cũng cho phép thay đổi giá trị các params đầu vào của api.

3. Cú pháp OpenAPI 2.0 (hay Swagger 2.0):

Ứng dụng này sử dụng cú pháp OpenAPI 2.0 để viết tài liệu API, bạn xem tài liệu sau của Swagger để viết được tài liệu api đúng cú pháp: https://swagger.io/docs/specification/2-0/basic-structure/
Ứng dụng này mặc định sử dụng định dạng tài liệu YAML, bạn có thể cấu hình thành định dạng JSON nếu muốn.
Đặc tả OpenAPI 3.0 mới được đưa ra vào tháng 07/2017 nên hiện tại swagger-node chưa kịp cập nhật. Swagger-editor và swagger-ui thì đã được cập nhật lên đặc tả OpenAPI 3.0 nhưng nó làm việc với nhau rời rạc, hơn nữa Swagger-editor hiện tại chưa hỗ trợ save to backend tài liệu api mà bạn phải save về máy rồi upload file YAML (JSON) lên, rất bất tiện.
Chúng ta cùng chờ swagger-node được upgrade lên đặc tả OpenAPI 3.0, hoặc bạn hãy join vào contribute cho code của swagger-node có thêm tính năng này :P
Tham khảo:
https://github.com/swagger-api/swagger-node
https://community.apigee.com/questions/4877/getting-started-with-swagger-node-apigee-127-and-s.html

Bình luận


White
{{ comment.user.name }}
Bỏ hay Hay
{{comment.like_count}}
Male avatar
{{ comment_error }}
Hủy
   

Hiển thị thử

Chỉnh sửa

White

Kong Minh

1 bài viết.
0 người follow
Kipalog
{{userFollowed ? 'Following' : 'Follow'}}
{{like_count}}

kipalog

{{ comment_count }}

bình luận

{{liked ? "Đã kipalog" : "Kipalog"}}


White
{{userFollowed ? 'Following' : 'Follow'}}
1 bài viết.
0 người follow

 Đầu mục bài viết

Vẫn còn nữa! x

Kipalog vẫn còn rất nhiều bài viết hay và chủ đề thú vị chờ bạn khám phá!