Yapi结合swagger备注自动生成接口文档

Yapi结合swagger备注自动生成接口文档

TP5适用

例项目名称tp5

文件public下下载swagger-ui（只需要dist下的文件）

git clone .git

然后打开下载好的文件夹，找到dist目录, 打开index.html把其中的那一串url改成自己的url，就是第一步中的创建好的那个url,记得后面加上swagger.json,即localhost/tp5/swagger-ui/swagger.json

<script>
load = function() {// Build a systemconst ui = SwaggerUIBundle({url: "localhost/tpSwagger/tp5/swaggerApi/swagger.json", // 更改此url为你的urldom_id: '#swagger-ui',presets: [SwaggerUIBundle.presets.apis,SwaggerUIStandalonePreset],plugins: [SwaggerUIBundle.plugins.DownloadUrl],layout: "StandaloneLayout"})window.ui = ui
}
</script>

改完之后，访问下你的swagger-ui中index所在的url：localhost/tp5/swagger-ui/index.html，显示的内容应该为：Failed to load spec.

安装swagger-php后端(第三方类)

进入tp框架找到根目录下的composer.json，打开它并向其中的require中添加：

（tp5用的  "zircote/swagger-php": "^3.0"  ）

// 找到此文件的require，在后面直接添加
"zircote/swagger-php": "*"// 添加前
"require": {"php": ">=5.4.0","topthink/framework": "^5.0",},// 添加后
"require": {"php": ">=5.4.0","topthink/framework": "^5.0","zircote/swagger-php": "*"},

然后进入到此目录下（在此目录下shift+右键，选择在此处打开命令窗口），运行

composer update

等待安装完成或者直接在打开命令窗口之后运行

composer require zircote/swagger-php

提示安装完成后执行

composer global require zircote/swagger-php

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

生成swagger.json文件（swagger-php3.0版本bin/openapi 之前版本为bin/swagger ）

php D:/phpstudy/WWW/tp5/vendor/zircote/swagger-php/bin/openapi D:/phpstudy/WWW/tp5/vendor/zircote/swagger-php/Examples -o D:/phpstudy/WWW/tp5/public/swagger-ui/swagger.json

（坑）tp5执行报错（think-captcha 12行）

composer更新topthink/think-captcha类

找到根目录下的composer.json，删除topthink/think-captcha类，打开命令框执行

composer require topthink/think-captcha

安装成功后再次执行生成swagger.json文件命令

ThinkPHP5中直接使用swagger

在tp5中写一个公用的方法，每次访问页面就直接调用此方法生成swagger.json文件，然后跳转到swagger的页面。首先把D:/phpstudy/WWW/tp5/vendor/zircote/swagger-php/Examples中的例子复制到你的application中，这样你的项目中就有了写好的可以测试的文件；然后写控制器中的方法：

<?php
namespace appindexcontroller;use thinkController;
class Index extends Controller
{public function index(){$path = 'D:/phpstudy/WWW/tp5/application'; //你想要哪个文件夹下面的注释生成对应的API文档//(坑 3.0后Swagger变为openapi新本版需要转json化 原语句：$swagger = Swaggerscan($path);)$swagger = openapiscan($path);$swagger = json_encode($swagger);// header('Content-Type: application/json');// echo $swagger;$swagger_json_path = 'D:/phpstudy/WWW/tp5/public/swagger-ui/swagger.json';$res = file_put_contents($swagger_json_path, $swagger);if ($res == true) {$this->redirect('localhost/tp5/swagger-ui/index.html');}}}

直接访问index方法，就会跳转到swagger的index.html 可以展示接口列表

备注写法

在你的class前⾯加⼊这样的⼀个代码

/*** @OAInfo(*     title="Auth API",*     version="1.0"* )*/
这个是申明⽂档的标题及版本，注意：代码中只⽤加⼀个这个就可

/*** @OAPost(*     tags={"首页"},   //分组名称*     path="/index/banner",  //接口地址*     summary="幻灯片",   //接口名称*     @OARequestBody(*         @OAMediaType(*             mediaType="application/json",  //格式*             @OASchema(*                 @OAProperty(               //参数*                     property="identity",*                     type="string"*                 ),*                  @OAProperty(               //参数*                     property="type",*                     type="string"*                 ),*                 example={"identity": 10,"type": 1}   //参数示例*             )*         )*     ),*     @OAResponse(             //响应数据*         response=200,*         description="OK"*     )* )*/

详细说明：版本说明 · Thinkphp集成Swagger-PHP · 看云

tp6引用

（加坑）更新完topthink/think-captcha类后再次执行生成swagger.json文件命令行运行报错'thinkConsole' not found

解决：把vendor/topthink/think-worker/src/command 下的 注释 掉

thinkConsole::addDefaultCommands(['worker:gateway' => '\think\worker\command\GatewayWorker','worker:server'  => '\think\worker\command\Server','worker'         => '\think\worker\command\Worker',
]);

然后在自己的应用里面的command.php 把下面这段复制进去数组

 'worker:gateway' => '\think\worker\command\GatewayWorker','worker:server'  => '\think\worker\command\Server','worker'         => '\think\worker\command\Worker',

执行成功

tp6中使用swagger公用的方法报错，暂未解决