Với những vai trò to lớn của mình, API ngày càng được ứng dụng nhiều trong cuộc sống số. Nó cung cấp tiêu chuẩn RESTfull APIs trên nhiều dịch vụ thông qua hệ thống internet. Những đối tác sử dụng dịch vụ đó đương nhiên phải hiểu được tài nguyên mà mình được cung cấp từ RESTfull APIs là gì, cách lấy chúng ta sao? Khi đó công cụ swagger sẽ được giới thiệu như một giải pháp tốt nhất phục vụ nhu cầu này. Vậy swagger là gì? Làm sáng tỏ điều này qua bài viết dưới đây nhé.
1. Swagger là gì?
Swagger chính là công cụ mã nguồn mở (open source) được dùng phục vụ cho mục đích xây dựng, phát triển nguồn tại liệu cho RESTfull Web Service cho hệ thống Open API. Bản Demo của swagger được trình bày như sau.
Công cụ swagger cung cấp các tính năng hỗ trợ đối với việc tạo các tài liệu doc bao gồm Swagger Editor, Swagger UI, swagger Hub, swagger Codegen, swagger Inspector. Trong số đó, 3 công cụ gồm swagger Hub, Open source và công cụ swagger Inspector là công cụ tiện ích cao cấp cho nên khách hàng sẽ phải trả phí cho chúng sau khi đã được trải nghiệm free trong thời gian 30 ngày. Để thuận tiện và nắm bắt được ứng dụng của swagger một cách hiệu quả nhất thì chúng ta sẽ tập trung tìm hiểu sâu vào các document APIs thông qua công cụ swagger.
Swagger UI được các nhà lập trình sử dụng cho mục đích phát sinh giao diện cho tài liệu theo chuẩn OpenAPIs từ file Config. Nhờ đó, bản giao diện được hiện một cách rõ ràng.
Xem thêm: Tư duy thiết kế
2. Swagger có cấu trúc như thế nào?
Thông tin về cấu trúc của swagger được chia sẻ cụ thể ngay sau đây. Muốn hiểu rõ về swagger thì nhất định đừng bỏ qua nhé!
2.1. Info của swagger
Mỗi một OpenAPI Specifications đều được bắt đầu bằng key word OpenAPI nhằm khai báo các phiên bản. Phiên bản sẽ định nghĩa được tất cả cấu trúc API. Trong info chứa đựng thông tin của API bao gồm Title, des, version. Trong đó:
- Title là tên của API
- Des (Description) là những thông tin mô tả đầy đủ một cách ngắn gọn về API. Phần này các lập trình viên hoàn toàn có thể trình bày thành nhiều dòng. Chức năng của thẻ des là hỗ trợ Markdown.
- Info: bao gồm các thông tin về việc liên hệ, điều khoản sử dụng và chứng chỉ,…
- Version: chính là phiên bản của API.
2.2. BasePath và Path trong swagger
BasePath có vai trò là một đường truyền gốc dẫn tới các thư mục của API trong Project. Nói cách khác BasePath chính là trọng tâm của API. Nhiệm vụ của các lập trình viên đó chính là định nghĩa các Paths dựa vào những tham số, phương thức thuộc về API như post, delete, get, put,… Mỗi yếu tố nằm bên trong Path đều phục vụ hiệu quả cho API ở từng phương diện.
Chẳng hạn như Sumary sẽ mô tả một cách tóm tắt API; parameters là tham số được truyền vào bên trong API, có thể tiến hành set chúng, thực hiện mô tả chi tiết chúng hoặc là làm Validate. Lập trình viên có thể chỉ định 1 Model (Schema) nhằm định nghĩa cho tham số.
2.3. Parameters
Tìm hiểu cấu trúc của swagger
Những Parameters có rất nhiều khai báo ở phía sau "in", chúng bao gồm:
- in: body: giúp tạo ra input-text area để phục vụ việc nhập vào các data body request.
- in: path: tạo input nhập giá trị khai báo ở routes (chủ yếu là id
- in: formData: tạo input được định sẵn từ trước để nhập data theo các fiedls định sẵn.
- in: query: tạo input nhập giá trị dựa trên field đã định sẵn nhằm gửi các query request.
- in: header: dùng khai báo giá trị ở header của request cần truyền.
2.4. Một vài thành phần khác
Cùng với những cấu trúc trên, bên trong của swagger còn bao gồm các yếu tố sau đây:
- Tags
- Security Definitions: được dùng phục vụ cho việc cung cấp tài nguyên trong API
- Definitions
Xem thêm: Trang vàng doanh nghiệp
3. Hướng dẫn cách cài đặt swagger
Cài đặt swagger là một trong những nhiệm vụ cần thiết khi viết Document phục vụ cho việc xây dựng, thiết kế, phát triển API. Để tiến hành quá trình cài đặt swagger, bạn cần thực hiện các bước như gợi ý bên dưới.
3.1. Tải về thư việc swagger
Việc đầu tiên cần thực hiện khi tiến hành cài đặt swagger đó chính là tải thư viện Swagger – Project Github về máy. Copy dist ở project tải về vào trong project của bạn, tiếp đến chọn mục Render file index (đuôi html). Lúc này, root sẽ được trỏ tới file index.html trong swagger.
3.2. Tạo cấu trúc cho thư mục
Tạo cấu trúc các thư mục là nhiệm vụ cần thiết khi cài đặt Swagger vì nó hỗ trợ bạn quản lý hiệu quả API. Bạn sẽ cấu trúc hệ thống quản lý bằng cách chia nhỏ các file, phân chia thành các thư mục để tạo thành một cấu trúc theo mô hình như sau:
Dựa vào hệ thống trên, bạn dễ dàng nhận diện được sự bao hàm của các yếu tố một cách logic và dễ dàng ghi nhớ nhất. Cụ thể như sau:
- index.yaml: là một file config chính, có chưa paths của API.
- paths: bao gồm những file define chính, được chia ra theo controller.
- definitions chứa đựng mô tả object và được phân chia ra theo models.
- shared: gồm những khai báo được sử dụng chung như những pagination infor, errors phổ biến, hay bắt gặp.
3.3. Xây dựng cú pháp $ref trong swagger
Sử dụng $ref có thể giúp tách từng phần của file (.yaml) mà vẫn có thể gọi lại được. Vì thế mà việc tách cấu trúc dữ liệu ra riêng lẻ theo cấu trúc của thư mục đã nêu trên và sau đó lại gọi chúng lại trở nên yên tâm hơn, đồng thời cũng giúp cho (.yaml) mang theo cấu trúc logic, dễ đọc, dễ nhìn và hiểu được ngay từ những quan sát đầu tiên.
Vậy cú pháp hỗ trợ bạn tách file như thế nào thông qua việc sử dụng $ref? Chúng ta sẽ chia sẻ điều này ngay bên dưới nhé.
- Tiến hành trỏ tới lement cùng 1 file của document
- Trỏ tới element trong thư mục cha của document
- Trỏ tới element trong thư mục bất kỳ nào đó của document.
3.4. Tạo config để cấu hình APIs
1 file (.yaml) sễ có cấu trúc thông dụng, phổ biến như sau:
openapi: định nghĩa tất cả cấu trúc của (.yaml)
info: chứa thông tin APIs gồm title, des, version,…
des: mô tả APIs
version: phiên bản của APIs chế độ công khai (public)
title: tên của APIs
paths: APIs được cung cấp cho khách
definitions: định nghĩa các schema dùng bởi APIs/
…
Với Swagger, nó còn có khả năng hỗ trợ việc viết config dựa theo json – một loại định dạng khác nhưng chúng ta vẫn nên sử dụng định dạng phổ biến sẽ quen thuộc hơn.
Khi cài swagger, hãy lưu ý một vài hoạt động sau:
- Tạo ra file index.yaml để cấu hình APIs theo một cấu trúc quy định. Lưu ý, cấu trúc này có thể phân chia paths dựa vào controller.
- Tạo ra các file: paths/users.yaml, definitions/user.yaml, definitions/commons.yaml.
- Chỉnh sửa index.html
Sau khi đã tiến hành các hoạt động trên thì bạn hãy bắt đầu cho server khởi chạy và chờ đợi thành quả cài đặt swagger của mình ra sao nhé.
Như vậy, với bài viết này chúng ta đã có thể tìm hiểu được swagger là gì và hơn thế, nắm bắt được những thông tin vô cùng hữu ích như cấu trúc của swagger, cách cài đặt thư mục này sao cho hiệu quả. Nếu đã đọc đến đây, lập trình viên hoàn toàn có thể tự mình viết API bản docs mà không cần quá phụ thuộc vào Ruby Gem nữa rồi.
Tham gia bình luận ngay!