ApiBlueprint在laravel框架中的使用

說明

API Blueprint is simple and accessible to everybody involved in the API lifecycle. Its syntax is concise yet expressive. With API Blueprint you can quickly design and prototype APIs to be created or document and test already deployed mission-critical APIs

通俗一點就是一種接口規範，並且是使用markdown的，使用markdown的語法書寫接口。

背景

目前和前端聯調、其餘部門聯調使用的方式有：

1. 使用MarkDown出接口文檔，放在共同的gitlab倉庫上面，先後端均可以訪問（只要約定好誰修改就行了，避免兩我的都修改出現差別），做爲一個常常寫方法註釋的好程序員來講（其實你的leader也會要求你），要在每個接口上面寫上幾行方法註釋，註明這個方法是作啥的，否則別人接手不便捷 ^_^；
2. 使用apiDoc工具（使用方法能夠查看：http://birjemin.com/wiki/php-apidoc），將相應的接口規範以註釋的方式寫在每個方法上面，而後生成相應的apiDoc文檔（只須要寫一下注釋，不須要再寫接口文檔啦~），經過node服務搭建一個服務環境，前端直接訪問個人開發機進行查看啦~
3. 使用birjemin/blueprint+aglio/macdown...組合，好比在接口的方法上面按照必定的格式進行註釋，而後使用該composer包生成apib文件，這個文件是一個遵循blueprint接口規範的markdown文件。可使用aglio插件搭建一個web服務（這個插件支持實時更新，不須要刷新頁面），也可使用macdown編輯器查看這個文件。

搭建步驟

1.安裝aglio（npm是啥？？？本身問前端同窗吧。。）

npm install -g aglio

請檢查是否安裝成功。

2.給laravel項目引入composer包（包已經提交，不過國內鏡像還沒同步）

composer require birjemin/blueprint dev-master

or

composer require birjemin/blueprint

3.在app.php中添加BlueprintServiceProvider::class

4.給接口添加註釋，添加在Controller入口方法前面(詳細的註釋方式請查看https://github.com/dingo/api/wiki/API-Blueprint-Documentation)。

/**
  * Class CarsController
  * @package App\Http\Controllers
  * @Resource("CarResource", uri="/api/cars")
  */
  class CarController extends Controller
  {
  /**
    * cars list
    *
    * Get current cars list
    *
    * @Get("/list")
    * @Transaction({
    *      @Request(identifier="page=1&type=1"),
    *      @Response(200, body={"msg": "返回成功","code": 200,"page": 1,"timestamp": "1522673813","data":{"result":[{"price": "2200","type": "福特","notice": "豪車"},{"price": "2200","type": "大衆","notice": "車"}]}})
    * })
    * @Parameters({
    *      @Parameter("page", type="integer", required=true, description="分頁", default=1),
    *      @Parameter("search", type="string", required=false, description="搜索條件"),
    *      @Parameter("type", type="integer", required=true, description="汽車類型", default=1, members={
    *          @Member(value="1", description="新車"),
    *          @Member(value="2", description="舊車")
    *      })
    * })
    */
    public function index()
    {
      return json_decode('{"succ":true,"code":0,"message":"","data":{"result":true}})');
    }
  }

@Response(200, body={...}中的 [和 ]要替換成 {和 }，這裏不替換是由於個人博客使用了 jekyll,github報錯啦~~

5.建立apib文件

php artisan birjemin:docs --output-file=tianming.apib

項目下面生成了tianming.apib文件，這個是一個markdown文件，能夠直接用markdown編輯器打開，下面講一下aglio的web服務。

6.運行aglio服務(詳細的命令能夠去https://github.com/danielgtaylor/aglio查看)

aglio -i tianming.apib -s

7.訪問:http://27.0.0.1:3000(端口能夠自定義，這個是默認的)

注意點

1.返回的數據不能夠json若是是數組,{}代替[]這個符號，好比示例中的。

{"msg": "返回成功","code": 200,"page": 1,"timestamp": "1522673813","data":{"result":[{"price": "2200","type": "福特","notice": "豪車"},{"price": "2200","type": "大衆","notice": "車"}]}}

就要將裏面的中括號替換成大括號！

2.這些註釋寫錯了會報錯哦~

3.和apidoc的註釋有區別~~

補充文檔

• https://apiblueprint.org/
• https://github.com/danielgtaylor/aglio
• https://github.com/dingo/api/wiki/API-Blueprint-Documentation

參考

1. https://apiblueprint.org/
2. http://www.piaoyi.org/php/DingoApi-Laravel-tips.html
3. https://github.com/danielgtaylor/aglio
4. https://github.com/dingo/blueprint
5. https://github.com/dingo/api/wiki/API-Blueprint-Documentation
6. https://github.com/monkeycraps/blueprint