Mục lục
Cài đặt API Blueprint và Aglio
API Blueprint hỗ trợ viết tài liệu cho các nền tảng ngôn ngữ khác nhau khá là đơn giản, họ cung cấp cho chúng ta các tiện ích Ruby, Net và một plugin Sublime text để tạo ra tài liệu nhưng có lẻ công cụ Aglio có lẽ đơn giản và dễ dùng nhất trong việc tạo ra một tài liệu, để cài đặt nó yêu cầu máy bạn phải có Node js nếu bạn chạy Mac OS, thì chỉ cần chạy lệnh sau:
brew install node
còn nếu bạn dùng Linux(fedora) thì cài đặt như sau:
sudo yum install node
Xin lỗi Windows fan tôi không dùng nó :), kế đến bạn cần cài API Blueprint tương tự nếu Mac OS
brew install --HEAD \
https://raw.github.com/apiaryio/drafter/master/tools/homebrew/drafter.rb
Nếu bạn dùng Linux chỉ cần chạy lệnh dưới đây
git clone --recursive git://github.com/apiaryio/drafter.git
cd drafter
make drafter
sudo make install
Vì như trên chúng tôi đã nói dùng Aglio đễ tạo một cách nhanh chóng cho tài liệu, chĩ cần chạy lệnh bên dưới là bạn có thể cài đặt nó
sudo npm install -g aglio
tham số g ở trên có nghĩa là chúng tôi cài nó cho toàn bộ app chạy node js, có nghĩa là bạn có thể gọi nó bất cứ chỗ nào trên máy của bạn. Nếu mọi thứ diễn ra tốt đẹp thì bạn chuyển sang bước kế tiếp:
Cách sử dụng Aglio
Mặc định nó có một ví dụ cho bạn tham khảo, bạn có thể chạy lệnh dưới đây để tham khảo ví dụ của nó:
cd ~/phanbook-api/docs
cat example.md
Để xem các Aglio có hỗ trợ các dòng lệnh nào bạn chỉ cần gõ lệnh sau:
$ aglio help
Usage: aglio [options] -i infile [-o outfile -s]
Examples:
aglio -i example.md -o output.html Render to HTML
aglio -i example.md -s Start preview server
aglio -t flatly -i example.md -s Custom template
aglio --no-condense -i example.md -s Disable options
Options:
-i, --input Input file
-o, --output Output file
-t, --template Template name or file [default: "default"]
-f, --filter Sanitize input from Windows [default: true]
-c, --condense Condense navigation links [default: true]
-w, --full-width Use full window width [default: false]
-s, --server Start a local live preview server
-h, --host Address to bind local preview server to [default: "127.0.0.1"]
-p, --port Port for local preview server [default: 3000]
-l, --list List templates
dưói đây là các lệnh mà chúng tôi thường sử dụng trong các tài liệu API của chúng tôi
# Default template
aglio -i input.md -o output.html
# Get a list of built-in templates
aglio -l
# Built-in template
aglio -t slate -i input.md -o output.html
# Custom template
aglio -t /path/to/template.jade -i input.md -o output.html
# Run a live preview server on http://localhost:3000/
aglio -i input.md -s
# Print output to terminal (useful for piping)
aglio -i input.md -o -
# Disable condensing navigation links
aglio -i input.md --no-condense -o output.html
# Render full-width page instead of fixed max width
aglio -i input.md --full-width -o output.html
cho tới bây giờ bạn đã biết cách sử dụng Aglio phải không nào, vì vậy để tự động tạo ra tập tin html bạn chỉ cần chạy lệnh sau đây:
aglio -t slate -i example.md -o index.html
php -S localhost:8080
dòng lệnh đầu tiên có nghĩa là kiếm cái tập tin example.md sau đó biên dịch nó thành tập tin index.html, còn dòng lệnh thứ hai chỉ để khởi động server thông qua thư viện PHP cho việc test, bây giờ bạn chỉ việc gõ đường dẫn http://localhost trên trình duyệt nếu bạn thấy nó có dạng như hình bên dưới
Aglio cung cấp cho ta nhiều theme, nếu bạn muốn Flatly theme chỉ cần gõ lệnh sau:
aglio -t flatly -i example.md -o index.html
thì kết quả sẽ là như thế này
Nếu bạn muốn API dạng 3 cột thì bạn có thể chạy lện như bên dưới
aglio --theme-variables streak -i index.md --theme-template triple -o index.html
Xem demo tại đây https://goo.gl/68qMnJ
Cú pháp trong API Blueprint
Nó sử dụng định dạng là Markdown để viết và một số tùy chọn của API Blueprint mà họ gọi là định dạng “Blueprint format 1A”, bây giờ bạn hãy mở tập tin example.md để xem nó có dạng như thế nào
FORMAT: 1A
HOST: https://api.mywebsite.com
# API Title
[Markdown](http://daringfireball.net/projects/markdown/syntax) **formatted** description.
## Subtitle
Also Markdown *formatted*. This also includes automatic "smartypants" formatting -- hooray!
> "A quote from another time and place"
Another paragraph. Code sample:
```http
Authorization: bearer 5262d64b892e8d4341000001
```
And some code with no highlighting:
```no-highlight
Foo bar baz
```
<!-- include(example-include.md) -->
# Group Notes
Group description (also with *Markdown*)
## Note List [/notes]
Note list description
+ Even
+ More
+ Markdown
+ Model
+ Headers
Content-Type: application/json
X-Request-ID: f72fc914
X-Response-Time: 4ms
+ Body
[
{
"id": 1,
"title": "Grocery list",
"body": "Buy milk"
},
{
"id": 2,
"title": "TODO",
"body": "Fix garage door"
}
]
### Get Notes [GET]
Get a list of notes.
+ Response 200
[Note List][]
### Create New Note [POST]
Create a new note
+ Request
+ Headers
Content-Type: application/json
+ Body
{
"title": "My new note",
"body": "..."
}
+ Response 201
+ Response 400
+ Headers
Content-Type: application/json
+ Body
{
"error": "Invalid title"
}
## Note [/notes/{id}]
Note description
Như đã nói nó sử dụng Markdown bạn có thể tham khảo chi tiết nó tại đây, tuy nhiên nó vẫn có một chút khác biệt, để chúng tôi chỉ cho bạn thấy dưói đây:
Cấu trúc tài liệu API Blueprint
Tất cả các tài liệu của API Bluprint đều có các section, trong mỗi section đó có một nhóm đối tượng hoặc một định nghĩa tài nguyên nào đó được trình bày dưới dạng một tập hợp Markdown, bạn hãy xem ví dụ trên # API Title hoặc ## Subtitle chính là từ khóa mà ta định nghĩa cho tài liệu của chúng ta thông qua cú pháp Markdown. Nếu như bạn muốn định nghĩa dạng là danh sách(list) của sections đó thì khai báo nó như sau:
+ <keyword>
...
+ <keyword>
[...]
Từ khóa trong API Blueprint
Header keywords
- Group
- Data Structures
- HTTP methods (e.g. GET, POST, PUT, DELETE…)
- URI templates (e.g. /resource/{id})
- Combinations of an HTTP method and URI Template (e.g. GET /resource/{id})
List keywords
- Request
- Response
- Boddy
- Model
- Schema
- Header & Headers
- Value
- Attribute & Attributes
- Relation
Chú ý rằng bạn nên tránh dùng các từ khóa trên đây khi viết tài liệu, chỉ sử dụng nó để khai báo giống như những từ khóa trong các ngôn ngữ lập trình khác vậy:)
Identifier(định danh)
Một sectíon có thể có nhiều các định danh trong section đó. Một định danh là bất kỳ sự kết hợp không có sản phẩm nào của bất kỳ nhân vật ngoại trừ [,], (,) và xuống dòng ký tự, và một định danh thì không được chứa các từ khóa khai báo ở trên:
Description(chi tiết)
Như bất cứ tài liệu nào khác thì phần chi tiết của một tài liệu là nhất thiết phải có để cho ngưòi dùng có thể hiểu được bạn viết cái g, và bạn chỉ cần viết nó theo cú pháp Markdown là được nếu có thể bạn hãy tránh dùng các từ khóa đã định nghĩa ở bên trên.
Cấu trúc căn bản của một section
- Metadata section xem chi tiết tại dây
- API name & overview section
- Resource group section && Resource section && Resource model section
- Schema section
- Action section
- Request section and Response section
- URI parameters section
- Attributes Section and description
Kết luận
Trên đây chúng tôi chỉ cho bạn các khái niệm căn bản, khi đi vào thực tế để viết tài liệu API cho sản phẩm của bạn thì bạn sẽ tự động hiểu cách tạo cấu trúc của một tài liệu, bản thân tôi khi viết tài liệu của chúng tôi thì có công cụ này nó giúp cho ta việc tạo cấu trúc html nhanh nhất để đưa cho khách hàng của chúng ta.
Có lẻ công cụ này còn khá mới nên ít ngưòi dùng, sau khi đọc bài viết này tôi huy vọng bạn thích nó, nếu bạn có công cụ nào hay xin hãy chia sẽ bên dưới. Thanks!
