APIs (Application Programming Interfaces) đang ngày càng trở thành phổ quát, các dịch vụ trên Internet hồ hết đều sử dụng chuẩn RESTfull APIs để cung cấp cho những đối tác một phần tài nguyên của mình sử dụng. Vậy ta đề ra vướng mắc là làm thế nào để cho những đối tác biết mình được cung cấp những tài nguyên gì? Phải sử dụng những thông tin nào để sở hữu thể lấy được tài nguyên đó?

Chính vì thế, ta cần phải có một phương tiện tương trợ việc tạo document APIs giúp thuận tiện cho việc cung cấp về kiểu cách sử dụng tài nguyên thông qua APIs một cách hiệu quả. Hôm nay tất cả chúng ta sẽ tìm hiểu về 1 phương tiện khá nổi tiếng dùng để làm viết document APIs: Swagger.

Swagger là 1 trong open source dùng để làm phát triển, thiết kế, xây dựng và làm tài liệu cho những mạng lưới hệ thống RESTfull Web Service. Ta có demo của Swagger như sau: Swagger cung cấp những phương tiện tương trợ việc tạo doc: Swagger UI, Swagger Editor, Swagger Codegen, Swagger Hub, Swagger Inspector. Trong số đó 3 phương tiện trước nhất là open source, Swagger Hub và swagger Inspector là những phương tiện hạng sang hơn nhưng sẽ phải trả phí, tuy nhiên tất cả chúng ta có thể dùng không tính tiền trong vòng 30 ngày. Vậy để cho thuận tiện, tất cả chúng ta sẽ tìm hiểu các viết doc APIs bằng SwaggerUI.

Swagger UI là 1 trong phương tiện giúp tạo 1 trang html css mô tả về các APIs được cấu hình bởi 1 file .yaml. Ngoài ra, phương tiện này còn được chấp nhận ta mockup đến api đó để xem kết quả.

Trong Ruby on Rails hiện tại có gem swagger-docs và swagger-ui có hỗ trợ việc viết code ruby để render ra file yaml nhưng hiện tại vẫn còn một số lỗi như examples không thể hiện thị hay lỗi về sử dụng oneOf còn chưa được khắc phục và các gem này require rspec nên sẽ chỉ dùng tốt trên môi trường local. Do đó chúng ta sẽ tìm hiểu để viết trực tiếp bằng cú pháp yaml thay vì sử dụng gem.

1. Tải thư viện swagger

Các bạn clone project Github này về, sau đó hãy copy thư mục dist trong project đó vào project của bạn và chọn render file index.html trong thư mục dist. Như trong project của tôi sử dụng Ruby on Rails làm backend sẽ copy vào thư mục public/swagger và thêm vào file routes.rb root to: redirect(“/swagger/index.html”)

Bằng cách này đường dẫn root của app sẽ trỏ đến file index.html của swagger.

2. Cấu trúc thư mục

Để tiện cho việc quản lí các API, ta sẽ chia nhỏ file yaml thành các file và phân chia vào các thư mục. Cấu trúc cơ bản của thư mục như sau:

index.yaml là file config chính cho API docs, chứa các path

paths chứa các file define chính của các API, chúng ta sẽ chia theo controller để dễ quản lí

definitions chứa các mô tả về object cho API, chúng ta sẽ chia theo models

shared chứa các khai báo dùng chung như các errors thường gặp, pagination infor

3. Cú pháp $ref

Một chiếc khá hay của file .yaml là tất cả chúng ta có thể tách riêng từng phần và gọi lại chúng nhờ dùng $ref. Chính vì điều này, tất cả chúng ta có thể tách các cấu trúc tài liệu thành từng phần riêng biệt như cấu trúc thư mục ở trên rồi gọi chúng lại. Điều này giúp file .yaml của tất cả chúng ta có một cấu trúc xinh đẹp dễ đọc và dễ hiểu. Để biết cụ thể thì bạn cần đọc document của swagger.

Cú pháp để dùng $ref có thể được tóm tắt như sau:

• Trỏ đến lement của document nằm trên cùng 1 file -$ref: ‘document.json#/myElement’
• Trỏ đến element của document nằm trong thư mục cha – $ref: ‘../document.json#/myElement’
• Trỏ đến element của document nằm trong một thư mục bất kì – $ref: ‘../another-folder/document.json#/myElement’

2. Tạo config cấu hình các APIs của bạn

Cấu trúc cơ bản của một file .yaml trong Swagger như sau:

openapi: Phiên bản Swagger đang sử dụng, sẽ khái niệm toàn bộ cấu trúc file .yaml

info: tin tức của APIs, trong này sẽ chứa những phần: title, version, description, …

title: tên Open-APIs (thường là tên gọi sản phẩm project mình làm)

vertion: Phiên bản APIs public

description: Mô tả về APIs

security: Authentication mà APIs sử dụng để cung cấp tài nguyên

paths: Các APIs mà bạn cung cấp cho đối tác

definitions: Khái niệm các model sử dụng bởi APIs

Ngoài ra còn rất nhiều keyword khác có thể tham khảo ở trang document của Swagger.

Swagger cũng tương trợ viết config theo định dạng json, tuy nhiên tất cả chúng ta nên viết theo định dạng yaml.

Ta sẽ tạo file index.yaml với cấu trúc như sau để cấu hình các APIs:

– openapi: 3.0.1 info: title: API V1 version: v1 paths: /api/v1/users: $ref: ../paths/users.yaml#index_create /api/v1/users/{id}: $ref: ../paths/users.yaml#show_update servers: – url: https://{defaultHost} variables: defaultHost: default: www.example.com

Ở đây chúng ta sẽ có chia paths theo controller, cấu trúc Restful trong rails có 7 action nhưng thông thường khi viết API thì chỉ có 5 action thường dùng là index, create, show, update, delete. Trong đó, index và create không yêu cầu ID, còn các action còn lại đều yêu cầu ID, với mục đích mỗi file .yaml trong paths sẽ khai báo 1 resource theo controller do đó ta cần thêm key index_create và show_update (key có thể đặt tùy ý) để phân biệt.

File paths/users.yaml

index_create: get: summary: List users tags: – users description: Use this API to get list users responses: 200: description: Get list users successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object properties: users: type: array items: $ref: “../../definitions/user.yaml” show_update: put: summary: Update user tags: – user description: Use this API to updat user parameters: – name: id in: path required: true schema: type: integer requestBody: content: application/json: schema: type: object properties: user: type: object properties: name: type: string required: true example: User new name responses: 200: description: Update user successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object properties: user: $ref: “../../definitions/user.yaml” meta: type: object 400: description: Bad Request content: application/json: schema: $ref: “../../definitions/common.yaml#/errors_object” examples: when name was blank: value: success: false errors: – resource: user field: name code: 1003 message: Name is blank 404: description: Not found content: application/json: schema: $ref: “../../definitions/common.yaml#/errors_object” examples: when user was not found: value: success: false errors: – resource: user field: code: 1051 message: User not found

File definitions/user.yaml

type: object properties: id: type: integer example: 1 name: type: string description: User’s name example: Nhat

File definitions/commons.yaml

errors_object: type: object properties: success: type: boolean example: false errors: type: array items: type: object properties: code: type: integer required: true message: type: string required: true resource: type: string nullable: true description: The resource which is error field: type: string nullable: true description: The attribute wich is incorrect

Chỉnh sửa file index.html trong thư mục swagger

window.onload = function() { // Begin Swagger UI call region const ui = SwaggerUIBundle({ url: “/api/v1/index.yaml”, dom_id: ‘#swagger-ui’, deepLinking: true, presets: [ SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset ], plugins: [ SwaggerUIBundle.plugins.DownloadUrl ], layout: “StandaloneLayout” }) // End Swagger UI call region window.ui = ui }

Sau tất cả bạn hãy khởi chạy server để xem thành quả của mình nào.

Như vậy chúng ta đã tìm hiểu và viết được một API documents cơ bản bằng cú pháp yaml với swagger. Ngoài ra chúng ta còn phân chia được các file yaml thành các thư mục phù hợp với cấu trúc viết API với Ruby on Rails để có thể dễ dàng quản lí. Swagger còn rất nhiều keyword thú vị để chúng ta có thể tìm hiểu và áp dụng vào project của mình. Và bây giờ chúng ta có thể viết API docs mà không còn phụ thuộc vào Ruby gem nữa.