swagger生成接口文档php项目,thinkphp结合swagger自动生成接口文档

1、swagger安装

第一步：安装swagger-ui前端

去这里下载https://github.com/swagger-api/swagger-ui

下载完成之后，将文件夹放到你的网站根目录上面，例如我是放在我wamp下面的www目录。

接着找到dist目录, 打开index.html把其中的那一串url改成自己的 比如http://localhost/tp/public/swagger.json

注意这个url就是后面swagger.json 的路径；

如果你想支持中文在index.html中加上

然后打开URL输入http://localhost/swagger-ui/dist/index.html就可以看到前端界面了, 应该是没内容的, 因为还没生成swagger.json, 生成好之后你设置的URL就起了作用。swagger.json我是放在tp框架下的swagger-docs目录中的，具体路径看你自己，具体下面会提到，不要慌O(∩_∩)O~。

第二步：安装swagger-php后端

进入你的项目目录执行如下命令：

composer require zircote/swagger-php

提示安装完成后会在你tp项目的vendor中生成一个zircote的组件文件夹，说明已经安装插件成功了。

第三步：生成swagger.json文件

方法1、直接在命令行中输入：

php D:\Program\www\tp\vendor\zircote\swagger-php\bin\swagger D:\Program\www\tp\application\app\controller\ -o D:\Program\www\tp\public

注意：第一个路径是你安装成功后组件的路径；

第二个路径是你想要生成这个目录下所有用swagger方式注释的php文件，把所有注释生成api文档；

第三个路径是你存放生成swagger.json的路径

方法2、编写控制器方法生成swagger.json：

如果我们每次修改了api，还要手动执行第三步的代码，有些繁琐，那我们就在控制器中写一个方法，每次访问swagger-ui的时候自动执行，然后跳转到前台swagger界面中。

下面是控制器里面的方法

$path = '../application'; //你想要哪个文件夹下面的注释生成对应的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');

}

第四步：编写swagger注释

控制器的注释写法

/**

* @SWG\Resource(

* basePath="http://skyapi.dev",

* resourcePath="/vps",

* @SWG\Api(

* path="/vps",

* @SWG\Operation(

* method="GET",

* type="array",

* summary="Fetch vps lists",

* nickname="vps/index",

* @SWG\Parameter(

* name="expand",

* description="Models to expand",

* paramType="query",

* type="string",

* defaultValue="vps,os_template"

* )

* )

* )

* )

*/

class VpsController extends Controller

{

// ...

}

这只是个简单的实例具体的注释写法请自己百度

2、swagger注释使用

参考这个(写的比较全面)：https://learnku.com/laravel/t/7430/how-to-write-api-documents-based-on-swagger-php#747b67

目前还没看出头绪，明天接着看吧