[以下内容来自本人一边做一边记录。本打算直接录视频，但发现有些问题更需要先解决。固先发文字教程]
[虽然还不太会录，但是今天还是录成了视频]
一，安装配置 TP6，及多应用。
【这里就不说了,自行查看】
官方手册 https://www.kancloud.cn/manual/thinkphp6_0
二，打开 php 项目安装 swagger-php 扩展
composer require zircote/swagger-php
三，为 swagger 添加路由
注意：分别在多应用的路由中写路由，而不是到全局路由中写
比如：项目下有 三个应用 index(pc站应用) api(前台接口应用) admin（后台接口应用）
因为，api和admin应用需要生成文档，所以在其下的路由中书写，不需要的应用就不用管它。
我的例子中路径分别为：
app\api\route\route.php 中内容如下：
<?php
use think\facade\Route;
Route::get('/swagger', function() {
$openapi = \OpenApi\scan('../app/api/controller');//各应用下的controller
header('Content-Type: application/json');
echo $openapi->toJson();
});
app\admin\route\route.php （照着上面写，记得把路径中的api改成admin）
四， 下载 swagger 的用户界面 swagger-ui
下载，clone 都行。 你自怎么用方便就怎么用
git clone https://github.com/swagger-api/swagger-ui.git
解压后项目根目录下的 public 下 swagger-ui 目录
修改 public/swagger-ui/dist/index.html 文件中的 数据来源
如下：
// url: "https://petstore.swagger.io/v2/swagger.json", // 这里是官方给的实例接口数据
url: "/swagger/docs/swagger.json", //这里是我们自己项目中自动生成的接口数据
还有语言 en 改为 zh-cn 。也可以不管它
五，建控制器 Swagger.php (注意：很多教程都掉了这一步，以讹传讹。这也是我会去亲测后，发完整教程的原因。)
在需要生成文档的应用下的 controller 目录下建控制器
这里的控制器名称来源于第三步中写的路由地址 swagger
Swagger.php 中 只需要有类 Swagger 就可以了，不用写方法。
同时写入文档配置信息（共用的部份），以后要改也方便，只需要改这个文件里的配置
如下：
<?php
namespace app\api\controller;
use think\Request;
use app\api\Base;
/**
* @OA\Swagger(
* schemes={"http","https"},
* host="api.cnfeicui.com",
* basePath="/",
* @OA\Info(
* version="1.0.0",
* title="中国翡翠API-【前台：支持在线测试】",
* description="注：请在接口路径前加上应用地址!如下<br>1、线上<br>前台API添加：http://api.cnfeicui.com/<br>后台api添加：http://api.admin.cnfeicui.com/<br>2、线下<br>前台API添加：http://api.dev.cnfeicui.com/<br>后台api添加：http://api.admin.dev.cnfeicui.com/",
* termsOfService="",
* @OA\Contact(
* email="admin@lck.yn.cn"
* ),
* @OA\License(
* name="cnfeicui",
* url="https://api.cnfeicui.com"
* )
* ),
* @OA\ExternalDocumentation(
* description="http://www.lck.yn.cn",
* url="http://www.lck.yn.cn"
* )
* @OA\SecurityScheme(
* type="http",
* in="header",
* name="Authorization",
* scheme="bearer",
* securityScheme="bearerAuth",
* bearerFormat="JWT"
* )
* )
*/
class Swagger extends Base
{
}
六，在需要生成文档的接口方法前，以 swagger 的要求写注释，即可自动生成接口文档
如需对登录（ Login.php ）接口生成文档。
<?php
namespace app\api\controller;
use app\api\Base;
use think\Request;
class Login extends Base
{
/**
* @OA\Post(path="/login/system",
* tags={"用户登录"},
* summary="系统帐号登录",
* @OA\Parameter(name="deviceid", in="header",description="设备唯一值",required=true,@OA\Schema(type="string")),
* @OA\RequestBody(
* @OA\MediaType(
* mediaType="content-type/json",
* @OA\Schema(
* @OA\Property(description="帐 号", property="identifier", type="string"),
* @OA\Property(description="密 码", property="credential", type="string"),
* required={"identifier","credential"})
* )
* ),
* @OA\Response(
* response="100",
* description="返回结果请以真实API拿数到数据为准",
* )
* )
*/
public function system(Request $request)
{
return json(['code'=>0,'msg'=>'这里是返回提示','data'=>[]]);
}
}
自此，swagger 就算配成功。
七，由于安全等多方面原因，我们生产环境是需要关闭 swagger 的
回到第三步，我们添加的路由文件中
先引入 Env
use think\facade\Env;
再修改路由方法：在其中加入环境变量判断。
在需要开启文档的环境 .env 文件中 配置 SWAGGER.START 的值为：true 。 未配置或 false 提示关闭
修改后的路由文件( route.php )如下：
<?php
use think\facade\Route;
use think\facade\Env;
Route::get('/swagger', function() {
if(Env::get('SWAGGER.START',0)){
$openapi = \OpenApi\scan('../app/api/controller');
header('Content-Type: application/json');
echo $openapi->toJson();
}else{
echo'{
"openapi": "3.0.0",
"info": {
"title": "中国翡翠API-【前台：支持在线测试】",
"description": "当前环境，已关闭！",
"termsOfService": "",
"contact": {
"email": "admin@lck.yn.cn"
},
"license": {
"name": "Private License",
"url": "URL to the license"
},
"version": "1.0.0"
},
"paths": {},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"name": "Authorization",
"in": "header",
"bearerFormat": "JWT",
"scheme": "bearer"
}
}
},
"externalDocs": {
"description": "http://www.lck.yn.cn",
"url": "http://www.lck.yn.cn"
}
}';
}
});
