Khi khai báo các request parameter, path parameter, request body, response body, … trong RAML, chúng ta cần khai báo kiểu dữ liệu của những thông tin này. RAML định nghĩa nhiều loại data types khác nhau giúp chúng ta có thể giải quyết những nhu cầu của mình. Trong bài viết này, chúng ta sẽ cùng tìm hiểu về data types trong RAML như thế nào, các bạn nhé!
Đầu tiên, các bạn hãy nhìn vào hình dưới, tổng quan thì RAML định nghĩa những loại data types được phân cấp như sau:
Như các bạn thấy, ở top của diagram trên, chúng ta có data type là any. Thông tin được định nghĩa với type any sẽ không có hạn chế gì cả, các bạn có thể định nghĩa số, chữ, đối tượng, bất cứ kiểu dữ liệu gì mà các bạn muốn.
Bên dưới data type any, chúng ta có các data type chi tiết, cụ thể hơn, hạn chế hơn nếu thông tin được định nghĩa bởi những data type này. Như các bạn thấy, chúng ta có các scalar types, array, object, union, XSD schema và cả JSON schema.
Scalar types
Nói nôm na scalar types là những kiểu dữ liệu đơn giản, không được định nghĩa từ những kiểu dữ liệu khác, ví dụ như boolean, string, null, file,… Giá trị của những thông tin được định nghĩa với những scalar types này là single, boolean thì chỉ có true, false; string thì giá trị chỉ là các chuỗi…
Date-only
Chúng ta chỉ khai báo ngày tháng năm cho kiểu dữ liệu này và tuân theo format được định nghĩa theo chuẩn Internet dành cho thời gian RFC 3339 các bạn nhé!
Ví dụ:
|
1 2 3 4 |
types: birthday: type: date-only example: 1987-06-24 |
Time-only
Ngược lại với date-only, kiểu dữ liệu này thì chỉ cho phép chúng ta định nghĩa giờ phút giây, nó không hỗ trợ ngày, tháng, năm với timezone và nó cũng tuân theo format RFC 3339 nha các bạn!
Ví dụ:
|
1 2 3 4 |
types: lunchtime: type: time-only example: 12:30:00 |
Datetime
Có 2 định dạng được hỗ trợ cho kiểu dữ liệu datetime là RFC 3339 và RFC 2616. Mặc định nếu chúng ta không báo format thì format được sử dụng sẽ là RFC 3339 các bạn nhé!
Ví dụ:
|
1 2 3 4 |
types: created: type: datetime example: 2021-11-30T16:41:41.090Z |
Datetime-only
Có thể nhiều bạn sẽ thắc mắc đã có kiểu dữ liệu datetime rồi thì kiểu dữ liệu datetime-only có ý nghĩa gì? Thật ra thì datetime-only là combine giữa date-only và time-only thôi các bạn, chúng được ngăn cách bởi chữ “T” và kiểu dữ liệu này không hỗ trợ timezone các bạn nhé!
Ví dụ:
|
1 2 3 4 |
types: pickup: type: datetime-only example: 2021-10-04T21:00:00 |
Number
Number là kiểu dữ liệu chung cho tất cả các kiểu dữ liệu liên quan đến số. Nó cho phép chúng ta định nghĩa giá trị nhỏ nhất minimum, giá trị lớn nhất maximum, format là gì: int, int8, int16, int32, int64, long, float, double.
Ví dụ:
|
1 2 3 4 5 6 |
types: weight: type: number minimum: -1.1 maximum: 20.9 format: float |
Integer
Đây là một kiểu dữ liệu kế thừa kiểu dữ liệu number với giá trị nguyên.
Ví dụ:
|
1 2 3 4 5 6 |
types: age: type: integer minimum: -3 maximum: 5 format: int8 |
Boolean
Giá trị của kiểu dữ liệu chỉ là true hoặc false, thể hiện tính đúng đắn.
Ví dụ:
|
1 2 3 |
types: isMarried: type: boolean |
String
Chúng ta có thể định nghĩa String theo pattern với minLength và maxLength, ví dụ như sau:
|
1 2 3 4 5 6 |
types: name: type: string pattern: ^.+@.+\..+$ minLength: 10 maxLength: 50 |
Null
Đây là kiểu dữ liệu cho phép field được không định nghĩa giá trị.
Ví dụ như nếu các bạn định nghĩa đối tượng Student với field name không được null như sau:
|
1 2 3 4 5 6 |
types: Student: type: object properties: name: string comment: string |
thì các bạn không được định nghĩa example như sau:
|
1 2 3 4 5 6 7 8 9 |
types: Student: type: object properties: name: string comment: string example: name: Khanh comment: |
Chúng ta có thể định nghĩa đối tượng Student như sau:
|
1 2 3 4 5 6 |
types: Student: type: object properties: name: comment: nil | string |
khi đó, chúng ta có thể định nghĩa example như sau:
|
1 2 3 4 5 6 7 8 9 |
types: Student: type: object properties: name: comment: nil | string example: name: Khanh comment: |
File
Kiểu dữ liệu này dành cho việc quản lý các thông tin liên quan đến file. Chúng ta có thể chỉ định định dạng tập tin, dung lượng minLength và maxLength tính theo byte cho kiểu dữ liệu này.
Ví dụ:
|
1 2 3 4 5 |
types: avatar: type: file fileTypes: ['image/jpeg', 'image/png'] maxLength: 307200 |
Array
Kiểu dữ liệu array thì giúp chúng ta định nghĩa mảng dữ liệu, có thể là mảng string, mảng number hoặc thậm chí là mảng các đối tượng, giống như trong Java đó các bạn!
Các bạn cần chỉ định rõ item trong array là kiểu dữ liệu nào, có cần unique hay không, và các bạn cũng có thể chỉ định giới hạn số lượng item trong array bằng minItems và maxItems.
Ví dụ:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
types: Student: type: object properties: name: string Students: type: Student[] minItems: 1 uniqueItems: true example: - name: Khanh - name: Phuc |
Object
Object thì giúp chúng ta định nghĩa thông tin về đối tượng, với nhiều properties thuộc về đối tượng này. Trong những ví dụ trên, mình có định nghĩa kiểu dữ liệu object cho Student.
Ví dụ:
|
1 2 3 4 5 |
types: Student: type: object properties: name: string |
Union
Union là kiểu dữ liệu giúp chúng ta có thể định nghĩa giá trị sử dụng nhiều loại data types khác nhau.
Ví dụ, properties name trong đối tượng Student sau có thể có kiểu dữ liệu là null hoặc string.
|
1 2 3 4 5 |
types: Student: type: object properties: name: nil | string |
XSD và JSON schema
XSD và JSON schema thì giúp chúng ta định nghĩa data types sử dụng schema của XML và JSON.
