安装

composer require michelf/php-markdown

API注释模板

/**
 * @Resource("Users", uri="/api")
 */
class UsersController extends BaseController
{
    /**
     * API标题
     *
     * API功能描述
     *
     * @Get("/users-detail/{$info}")
     * @Versions({"v1"})
     * @Transaction({
     *      @Response(200, body={"user":{"name":"张三","phone":"18501234567"}}),
     *      @Response(400, body={"error":"failed"})
     * })
     */
     public function user(){
     ...
     }

编写 dingo/api docs 注意事项:

  1. 注释里统一采用双引号
  2. 数组的方括号需要改写成花括号
  3. 多个@response 之间注意用 , 隔开
  4. @Get @Put @Post @Delete 注意首字母要大写

调试:

php artisan api:docs

Method

public function docs(Request $request)
    {
        $tmp_file = storage_path('app/api_docs.md');
        $command = '/usr/bin/php ' . base_path('artisan') . ' api:docs --name "官网 API v1" --use-version v1 --output-file ' . $tmp_file;
        //die($command);
        exec($command);
        $api_md = file_get_contents($tmp_file);
        $api_html = \Michelf\Markdown::defaultTransform($api_md);
        return $api_html;
    }