Sử dụng API Blueprint để viết tài liệu cho Restful web API

by Thien

on Jun 17/16 at 04:43

Ngày nay hầu hết khi ta viết một ứng dụng gì đó thường có một việc không thể thiếu đó là cung cấp API cho bên thứ ba để sử dụng, một khi ban công bố API thì điều đầu tiên cần có đó là tài liệu hướng dẫn, chúng tôi không thể hình dung việc một API cung cấp mà không có tài liệu thì như thế nào, chính vì nhu cầu đó nên có khá nhiều công cụ hỗ trợ cho chúng ta viết tài liệu, chẳn hạn như phpDocumentor, Swagger, nhưng có lẻ chúng tôi thấy API Blueprint có vẽ là dễ sử dụng và đẹp nhất, trong bài viết này chúng tôi sẽ hướng dẫn bạn tạo tài liệu bằng cộng cụ API Blueprint kết hợp với Aglio.

Bạn có thể xem một bản demo tại đây https://goo.gl/68qMnJ

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

Benchmark top page

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

Benchmark top page

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

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!