swagger

swagger 能帮助我们做那些事情

• 后端人员：规范约束自身Api，新手可以快速学习和尝试;
• 测试人员：多了一种测试手段。可以从横向的把控质量;
• 前端人员：设定契约，减少沟通，减少扯皮;

官方帮助手册&工具

https://swagger.io/docs/specification/what-is-swagger/ 手册

http://editor.swagger.io 语法测试工具

    git clone https://github.com/swagger-api/swagger-editor.git
    cd swagger-editor
    npm start

https://swagger.io/swagger-ui/ UI工具

PHP 如何编写？

https://github.com/zircote/swagger-php

注释添加

/**
 * @SWG\Info(title="My First API", version="0.1")
 */

/**
 * @SWG\Get(
 *     path="/api/resource.json",
 *     @SWG\Response(response="200", description="An example resource")
 * )
 */

解析

require("vendor/autoload.php");
$swagger = \Swagger\scan('/path/to/project');
header('Content-Type: application/json');
echo $swagger;

\Swagger\scan 是swagger php 组件的核心方法， 输入参数：当前项目路径，可以是字符串或数组，遍历路径下所有方法的注释，组合生成符合swagger规范的数据。