README

1. blueprint 是一个接口文档规范，特别适合用于 RESTful 接口描述 https://apiblueprint.org/
2. 为 Laravel 开发了一套工具，用于持续生成文档，并提供前后端调试

特性

1. 支持 RESTful 请求
2. 依赖 Laravel 的命令行
3. 修改了 dingo 的 blueprint 自定义支持
4. 修改 npm 包 aglio，提供直接在文档 H5 上进行调试
5. 可以根据需要生成所有接口，或者部分接口

示例

1. 结果

   • 
   • 可以指定 app_host，用于发送请求到不同的环境
   • 选择需要的接口进行调试
   • 直接发送请求，支持所有 RESTful 请求，使用 jQuery AJAX 实现
   • 需要安装 CORS Chrome 插件，用于跨域处理

2. composer 添加依赖

   • 依赖内网仓库 http://packagist.in66.cc:8080/

     "repositories": [
         {
             "type": "composer",
             "url": "http://packagist.in66.cc"
         }
     ]
     

   • composer require in/blueprint:dev-master

   • 在 Laravel 应用中添加 provider

     // api 工具
     In\Blueprint\Laravel\BlueprintServiceProvider::class,
     

3. 文件描述

   • 
   • 格式要求比较严格
   • 原始文档，https://github.com/dingo/api/wiki/API-Blueprint-Documentation
   • 坑点
     • 多个参数，要用 ',' 区分
     • 注意不能使用 '' 区分
     • @Response 返回的 body 有特殊要求，不支持 [] 数组类型，实际开发中，一般是生成一轮文档后，在 H5 页面上请求，能直接得到转换过的值
       • 

4. 运行生成命令

   • 生成所有文档，会扫描 app\Http\Controllers 里的所有文件 php artisan blueprint:generate
   • 生成单个 controller 的文档，php artisan blueprint:generate app/Http/Controllers/WechatCorp/WechatCorpController.php
     • 
     • 图示的是生成的文件位置

5. 展示控件安装

   • 需要在内网安装
   • npm install -g git+ssh://git@githost.in66.cc:yidu/aglio.git

6. 运行展示

   • 安装后会多了一个 aglio 的命令，默认端口 3000，也能生成静态文件
   • aglio -i storage/api/blueprint.apib -s -h 0.0.0.0
   • aglio 是基于 https://github.com/danielgtaylor/aglio 修改的

持续特性

1. 支持内部类文档，主要是针对 Laravel 系列的 job, listener, facade, service
2. 增加 JSON schema 的验证
3. 接入到公司的 Jenkins 测试中

API Blueprint Generator

此包从类集合生成有效的 API Blueprint 1A 文档。

用法

一些索引方法 phpdoc 示例

<?php

/**
 * Products
 *
 * @Resource("Products", uri="/products")
*/
class ProductsController extends ApiController
{
    /**
     * Products list
     *
     * Get current products list
     * 
     * @Get("/")
     * @Versions({"v1"})
     * @Transaction({
     *      @Request(identifier="/?state=synced"),
     *      @Response(200, body={"data":{{"id":"rkoVJ7qa4Z6lzXdVnldgx9LmpBP0DQ3e","name":"Product name","status":"active"}},"meta":{"pagination":{"total":1,"count":1,"per_page":1,"current_page":1,"total_pages":1,"links":{}}}})
     * })
     * @Parameters({
     *      @Parameter("api_token", type="string", required=true, description="API Token", default=null),
     *      @Parameter("page", type="integer", required=false, description="Pagination page", default=1),
     *      @Parameter("state", type="string", required=false, description="Product status filter", default="synced", members={
     *          @Member(value="synced", description="Products synced"),
     *          @Member(value="pending", description="Products pending")
     *      })
     * })
     */
    public function index(Request $request)
    {}
}

扩展

1. 添加 Laravel job 生成 API 文件
2. 应用主机

API 服务，针对 Laravel 部分

API 事件

API 门面

API 辅助函数

API 任务

API 命令

许可

此包在 BSD 3-Clause 许可证 下授权。