Viết document cho RESTful APIs bằng Swagger và Slate
documentation
4
swagger
1
slate
1
White

Nguyễn Hoàng Hüy viết ngày 26/03/2017

Hiện nay, các ứng dụng viết theo mô hình RESTful API và Software-as-a-Service (SaaS) ngày càng bùng nổ. Thế nên việc có 1 trang quản lý các api của mình một cách đẹp đẽ, khoa học là 1 điểm cộng vô cùng lớn, bởi vì hầu hết các developers đều nhìn vào trang này trước khi nhìn xem code có tốt hay không. Vậy nên trong bài viết của mình sẽ hướng dẫn việc tạo nên 1 trang quản lý document cho API bằng 2 công cụ là SwaggerSlate

Swagger và Slate là gì ?

Swagger:

Swagger là một công cụ open source khá đơn giản nhưng lại vô cùng mạnh mẽ. Swagger cung cấp 3 tools chính cho các developers :

  • Swagger-Editor : dùng để design lên các APIs hoàn toàn mới hoặc edit lại các APIs có sẵn thông qua 1 file config
  • Swagger-Codegen : dùng để generate ra code từ các file config có sẵn
  • Swagger-UI : dùng để generate ra file html,css,... từ 1 file config

Do cung cấp các tool khá đa dạng nên việc viết document bằng swagger cũng có 2 cách tiếp cận:

  • Top-down approach: Nghĩa là chúng ta sẽ design lên các api trước khi viết code
  • Bottom-up approach: Nghĩa là từ các api có sẵn sẽ generate ra 1 file config

Slate:

Slate là một công cụ open source, nhiệm vụ chính (và duy nhất) của slate là generate ra các file html,css,... từ 1 file config .md . Ưu điểm của slate là UI cực kì đẹp và khoa học

Ngoài ra, vì chỉ cần config trên 1 file .md nên việc chỉnh sửa nội dung là hết sức đơn giản . Không những thế slate còn support syntax cho hơn 100 ngôn ngữ khác nhau nên việc viết example code cho api của mình không còn là vấn đề phải suy nghĩ tới

Vậy tại sao lại phải dùng Swagger + Slate

Như các bạn có thể thấy, ưu điểm của Swagger là việc chúng ta có thể generate ra 1 file config (ở đây là .json.yaml) từ chính code của chương trình . Tất nhiên để có thể generate ra thì code phải tuân theo quy ước của ngôn ngữ đó. Ở bài viết mình dùng Golang làm ngôn ngữ, các bạn có thể xem quy ước của Golang tại đây. Thế nhưng phần UI của swagger lại khá rườm rà không đẹp như slate. Ngược lại, UI của slate rất đẹp nhưng lại không thể generate ra file config như swagger

Vậy nên, những việc chúng ta sẽ làm là sẽ từ 1 file config.yaml của Swagger sẽ convert sang 1 file config.md và dùng Slate để generate ra các file html,css,... để publish ra bên ngoài

Các bước thực hiện

1) Chuẩn bị file config.yaml

Ở đây để cho đơn giản mình sẽ sử dụng file example của swagger, các bạn có thể tìm thấy các file tương tự tại đây

Các bạn chọn tab File và download file petstore_simple.yaml:

Ở bước này nếu bạn muốn sử dụng Swagger UI để publish trang document của mình thì các bạn có thể xem hướng dẫn khá chi tiết tại trang này

Trang nó sẽ ra như thế này:

alt text

2) Cài đặt tool swagger2slate

swagger2slate là 1 tool giúp chúng ta convert file có định dạng .json.yaml của swagger thành 1 file .md của slate. Tất cả những gì chúng ta cần làm là download swagger2slate.phar và cấp quyền execute cho file này

chmod +x swagger2slate.phar
echo -e "\nswagger2slate.phar" >> .gitignore

Sau đó tiến hành convert file petstore_simple.yaml thành file có định dạng .md bằng lệnh

./swagger2slate.phar convert ../{your-repository}/petstore_simple.yaml  -o petstore_simple.md
  • Note: Vì 1 lý do vô hình nào đó, swagger2slate chỉ support .json.yml chứ không phải là .yaml nên chúng ta sẽ tiến hành đổi tên file trước khi thực hiện lệnh convert
mv petstore_simple.yaml petstore_simple.yml

Sau khi thực hiện xong lệnh convert, chúng ta sẽ được 1 file petstore_simple.md. Tiếp theo chúng ta sẽ tiến hành cài đặt slate

3) Cài đặt Slate

Chuẩn bị :

  • Linux or OS X
  • Ruby, version 2.2.5 trở lên
  • Bundler gem install bundler

Bắt đầu cài đặt Slate thôi

1) Fork repository của slate về trang github của mình
2) Clone về máy local
3) cd tới directory slate

Lúc này directory slate của mình sẽ có dạng như sau

alt text

Trong đó:

  • directory source sẽ là file chúng ta sẽ thao tác
  • file index.html.md sẽ là file .md để generate ra các file html,css,...
  • directory includes là nơi chứa những api nhỏ hơn được tách từ file index.html.md nếu bạn muốn tách ra thành các file .md nhỏ hơn
  • Các directory còn lại là các css,logo,.. mặc định của slate, bạn có thể thay đổi các directory này để override các giá trị mặc định của slate

Okay, giờ chúng ta tiến hành copy file petstore_simple.md vào file index.html.md

cp petstore_simple.yaml  ../{your-slate-directory}/source/index.html.md

Bạn có thể xem hình hài trang web trước khi deploy bằng lệnh:

bundle exec middleman server

Sau đó mở trình duyệt đến http://localhost:4567 để xem trang mình đã tạo ra. Nếu tất cả đã hoàn thiện bạn bấm lệnh sau để tiến hành build:

bundle exec middleman build 

Kết quả sau khi chạy hàm đó sẽ như thế này:

alt text

Lệnh này sẽ tạo ra 1 directory build chứa file html và cái css bạn chỉ cần deploy directory này lên server của bạn.

Okay, xem trang của mình đã tạo ra xem nào:

alt text

Cài đặt languages tab trong slate

1 trong các tính năng mình thích của slate là việc tạo các languages tab cho example code vô cùng đơn giản và bản thân slate cũng support syntax cho khá nhiều ngôn ngữ.

Để thêm tính năng này vào trang của mình, các bạn mở file index.html.md trong directory source của slate và thêm các dòng này vào đầu file

language_tabs:
    -- go
    -- shell

Ở đây mình làm example code trên 2 ngôn ngữ là go và shell, tiếp theo khi viết example code các bạn chỉ cần viết như này:

alt text

hoặc như này:

alt text

Lời kết

Vậy là chúng ta đã hoàn thành xong việc viết 1 trang document cho RESTful API bằng việc sử dụng Swagger và Slate. Trong phạm vi bài viết, vì kinh nghiệm bản thân còn hạn chế nên việc sử dụng 2 tools trên còn ở mức khá đơn giản, chưa khai thác hết khả năng của cả 2 vậy nên nếu các bạn có kinh nghiệm nào trong việc sử dụng kết hợp 2 tools trên thì có thể đóng góp cho mình và các bạn khác bằng cách comment bên dưới :)

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

Nguyễn Hoàng Hüy

1 bài viết.
17 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.
17 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á!