Quantcast
Channel: 簡睿隨筆
Viewing all articles
Browse latest Browse all 897

撰寫API規格文件的利器:API Blueprint與aglio

$
0
0

API Blueprint是一個用來產生RESTful Web Services API規格的樣板語言,只要依它定義的格式寫好Markdown格式的文字檔,再使用輔助工具(有很多個,本文介紹的是aglio)就能產生標準、統一的API文件。相較於類似功能的SwaggerRAML,API Blueprint的最大優點就是撰寫容易快速,如果原本已經具有Markdown的使用經驗,那更是能在最短時間內就掌握好。

API Blurprint的基本格式範例如下:

FORMAT: 1.0
# API名稱

API說明

## 說明重點1

## 說明重點2

# Group 資源群組以 Group 開頭

## 資源 [/URI]

### 動作 [GET]

* Parameters
    * 參數1: `範例值` (required, 格式) - 參數說明
    * 參數2: `範例值` (optional, 格式) - 參數說明

* Response 200 (application/json)

        { "code": "OK", "message": "success" }

* Response 404 (application/json)

        { "code": "NOT_FOUND", "message": "No data" }

### 動作 [POST]

內容格式同 GET

### 動作 [DELETE]

內容格式同 GET

重點說明

  • 群組分類以 Group 開頭
  • Response裡的傳回範例以8個空白或兩個 Tab 開頭
  • 如果有多個API或多人同時撰寫時,可以用引入的方法把一個檔案拆成幾個檔案,如:
# Group 1. 城市資料
<!-- include(CITY.md) -->

# Group 2. 氣象資料 
<!-- include(WEATHER1.md) -->
<!-- include(WEATHER2.md) -->

將Markdown轉換為HTML

接著用 aglio 將Markdown格式的文字檔案轉換成HTML。aglio是Node.js的模組,安裝好Node.js後再用下列指定安裝aglio:

npm install -g aglio

執行轉換的命令:

aglio -i Markdown檔名  -o 產生的HTML檔名  [選項]
  • 選項:只執行aglio會列出所有選項的說明
  • 例如用 –theme-variables flatly 可以變更Default樣式為flatly樣式

範例

FORMAT: 1.0

# 城市與氣象資訊Web Services API

* 這是使用API blueprint撰寫的示範文件
* 由 [GlobalWeather Web Service](http://www.webservicex.net/globalweather.asmx?op=GetWeather) 取得相關資料

# Group 1. 城市資料

* 這是使用API blueprint撰寫的示範文件
* 由 [GlobalWeather Web Service](http://www.webservicex.net/globalweather.asmx?op=GetWeather) 取得氣象資料

## 依國名取回城市名 [/globalweather.asmx/GetCitiesByCountry?CountryName={CountryName}]

### 取回城市名 [GET]

* Parameters
    * CountryName: `Taiwan` (required, String) - 國名

* Response 200 (text/xml)

        <string xmlns="http://www.webserviceX.NET">
          <NewDataSet>
           <Table>
             <Country>Taiwan</Country>
             <City>Kangshan Tw-Afb</City>
           </Table>
           <Table>
             <Country>Taiwan</Country>
             <City>Chinmem / Shatou Air Force Base</City>
           </Table>
         </NewDataSet>
        </string>

# Group 2. 氣象資料 

* 這是使用API blueprint撰寫的示範文件
* 由 [GlobalWeather Web Service](http://www.webservicex.net/globalweather.asmx?op=GetWeather) 取得氣象資料

## 依城市名稱取回氣象 [/globalweather.asmx/GetWeather?CityName={CityName}&CountryName={CountryName}]

### 取回氣象資料 [GET]

* Parameters
    * CityName: `Taipei` (required, String) - 城市名
    * CountryName: `Taiwan` (optional, String) - 國名

* Response 200 (text/xml)

        <string xmlns="http://www.webserviceX.NET">Data Not Found</string>

sample

##

您可能也會有興趣的類似文章


Viewing all articles
Browse latest Browse all 897

Trending Articles