swagger-UI API管理工具,不用写接口文档的好东西

2016年12月5日

Swagger-UI 的官方地址:

http://swagger.wordnik.com

Github上的项目地址:

https://github.com/wordnik/swagger-ui

官方提供的demo地址

http://petstore.swagger.wordnik.com/

 

php vendor/zircote/swagger-php/bin/swagger app/ -o public/api-docs/swagger.json 运行生成api接口

第一个路径是你安装成功后组件的路径;第二个路径是你想要生成这个目录下所有用swagger方式注释的php文件,把所有注释生成api文档;第三个路径是你存放生成swagger.json的路径。

 

不想每次都运行上边的命令:下面就是做成自动加载(代码如下)

-------------

 

$path = 'E:\wamp64\www\tp'; //你想要哪个文件夹下面的注释生成对应的API文档
$swagger = \Swagger\scan($path);
//header('Content-Type: application/json');
//echo $swagger;
$swagger_json_path = $path.'/swagger-docs/swagger.json';
$res = file_put_contents($swagger_path, $swagger);
if ($res == true) {
   $this->redirect('http://localhost/swagger-ui/dist/index.html');
}
-------------

下面是是在tp的使用,讲得很清晰.很实用

https://github.com/fengdeqiao/swagger-thinkphp

 

下面主要说下,我在laravel中的使用.(laravel5.2版本中体验)

 

这里记录的是较为灵活的方案,不考虑使用swaggervel,具体使用参考一下步骤:

安装依赖swagger-php

composer require zircote/swagger-php

创建SwaggerController

php artisan make:controller SwaggerController

SwaggerController加上导出SwaggerJSON数据的处理

/**
 * @Swagger(
 *     schemes={"http"},
 *     basePath="/",
 *     consumes={"application/json"},
 *     tags={
 *         @SWG\Tag(
 *             name="API",
 *             description="API接口"
 *         )
 *     }
 * )
 *
 * @Info(
 *  title="API文档",
 *  version="0.1"
 * )
 *
 * @return mixed
 */
class SwaggerController extends Controller
{
    public function doc()
    {
        $swagger = \Swagger\scan(realpath(__DIR__.'/../../'));
        return response()->json($swagger);
    }
}

routes.php加上路由

Route::get('/swagger/doc', 'SwaggerController@doc');

接下来下载swagger-ui,将swagger-ui/dist目录内的文件拷贝于/public/swagger-ui目录下,可以尝试访问http://localhost/swagger-ui看看能否正常显示。

会发现文档地址还是例子的地址,可以修改public/swagger-ui/index.html文件下的默认地址

var url = window.location.search.match(/url=([^&]+)/);
if (url && url.length > 1) {
url = decodeURIComponent(url[1]);
} else {
url = "http://petstore.swagger.io/v2/swagger.json" //改成你的路由地址,如:/swagger/doc;
}

再刷新页面,或者强制刷新就可以使用了

No Comments

发表评论