README

专为 Thinkphp5 生成 swagger 注释文档.

项目简介

为了便于测试 API 接口，我们通常会选择书写 swagger 注释来生成相关文档，但书写注释是一项大量重复且技术含量不高的体力劳动，且容易出错。

该扩展包可以通过访问 API 接口时自动生成相应的 swagger 注释，从而告别手动书写注释。

目前生成的 swagger 注释支持 swagger-php ~2.0

安装

$ composer require tien/think-swagger

使用

生成方法体的 swagger 注释

前提：

以某个项目的 feedback 模块为例。
该模块下有 create, index, show, update 及 delete 五个 action。
该模块的访问地址是 http://domain.com/api/feedback/*****。
最佳使用体验是通过中间件，下面示例也是通过中间件完成的，若 TP 版本低于 5.1.6，请自行参考代码实现，谢谢！

在 feedback 模块的验证类代码如下：

use Tien\ThinkSwagger\Core; 	//需要引入 Core 类

class Feedback extends Validate
{
	use Core;		//需要引入 Core 类
	
	protected $rule = [
		'name|姓名' => 'require|max:32',
		'mobile|手机号' => 'require|mobile',
		'headImg|头像' => 'require|image',
		'resume|简历' => 'require|file',
		'token|会话密钥' => 'require|length:32',
		'id|反馈 id' => 'require|integer|gt:0' 
	];
	
	
	protected $scene = [
	 	'create' => ['token', 'name', 'mobile', 'headImg', 'resume'],
	];
	
	
	/**
	 * 需要增加一个数组，用来解释接口的作用
	 * 注意是 public 修饰
	 */
	public $tienText = [
		'create' => '新增留言,*****'
	];

}

中间件代码如下：

public function handle($request, \Closure $next)
{
	//存放生成 swagger 注释的文件路径
	$path = \think\facade\Env::get('app_path') . 'swagger/';
	
	//实例化对象
	$tien = new \Tien\ThinkSwagger\Method($path);
	
	/**
	 * 建议书写如下判断
	 * 若不是开发环境，直接结束该中间件
	 * 若在 .env 文件中配置了 APP_DEBUG 属性，那么判断如下。
	 * 如果没有配置，强烈建议自行判断
	 */
	if (!$tien->verifyIsDev()) {
		return $next($request);
	}
	
	/**
	 * 初始化信息
	 * 方法 setIgnoreRoute 忽略路由的前缀字符，不是必须的，可自行尝试
	 */
	$tien = $tien->setIgnoreRoute('api/')->initRequest($request);

	//需判断该注释体是否已存在，避免重复生成
	if (!$tien) {
		return $next($request);
	}
	
	//生成注释
	$tien->formatContent()->create();

	return $next($request);

}

生成注释

把该中间件注册到 feedback 模块中，建议添加到模块下的 middleware.php 文件。

再 POST 调用 create 接口的地址 http://****/api/feedback/create。

会在 application/swagger 目录下生成 Feedback.php 文件（若没有更改生成路径的话）。具体效果查看附录一。

自动替换

若我们继续完成 feedback 模块的 update 方法，当完成 scene.update 时，会发现很多验证规则已不再是 require 的了，比如 name, headImg 等字段不是必填的，而可能只有 id 及 token 是必填的，那么我们可以如下书写：

//Feedback 验证类中，还是引入了 \Tien\TienSwagger\Core 类。
protected $tienSupplySuffix = '_no';	//默认是 ‘_no’,可以更改



pretected $scene = [
	'create' => [……],
	'update' => ['token', 'id', 'name_no', 'mobile_no', 'headImg_no', 'resume_no'],		// 有 ‘_no’ 后缀的表示不是必填的
];

public $tienText = [
	'create' => '新增留言,*****',
	‘update’ => '更新留言，只能本人操作',
];

再 PUT 调用接口地址 http://***/api/feedback/update/1。

会在 application/swagger 目录下的 Feedback.php 文件中生成注释（若没有更改生成路径的话）。具体效果查看附录一。

获取添加后缀的验证规则

$validate = new \app\api\validate\Feedback();

$updateRule = $validate->getRuleByAction('update');

var_dump($updateRule); // 有 '_no' 后缀的，会替换掉 require 字符

生成 api 文档的简介

执行如下代码：

// swagger 文件路径
$path = \think\facade\Env::get('app_path') . 'swagger/';

//实例化对象
$summary = new \Tien\ThinkSwagger\Summary($path);

//生成注释
echo $summary->setFilename('Summary.php')
	->setSchemes(['http', 'https'])
	->setHost('127.0.0.1:8000')
	->setConsumes('multipart/form-data')
	->setProduces('application/json')
	->setVersion('V0.1')
	->setTitle('接口文档')
	->setDescription('Hello world think-swagger, 一个专门为 TP5 生成 swagger 注释的扩展包，可以更加具有对象特性')
	->formatContent()
	->create();

效果图查看附录一。

生成 api 模块的简介

执行如下代码：

// swagger 文件路径
$path = \think\facade\Env::get('app_path') . 'swagger/';

//实例化对象
$tag = new \Tien\ThinkSwagger\Tags($path);

$tagArr = [
	'Feedback' => '留言反馈',
	'Test' => '测试', 
];

//生成注释
echo $tag->setFilename() //默认 Tags.php
	->setTags($tagArr)
	->formatContent()
	->create();

效果图查看附录一。

额外提示

当生成 swagger 注释文档之后，应该通过 swagger-php 生成相应的 json 文件。在项目根目录下执行如下命令(详情 swagger-php)：

$ php ./vendor/zircote/swagger-php/bin/swagger ./application/ -o public/swagger.json

再通过 swagger-ui 解析生成的 swagger.json 文件（详情 swagger-ui）。

贡献

你可以通过以下三种方式之一进行贡献

使用 issue tracker 提交错误报告。
在 issue tracker 上回答问题或修复错误。
贡献新功能或更新 wiki。
相关问题也可以在 TP 论坛中讨论。

代码贡献过程并不正式。你只需确保遵循 PSR-0, PSR-1, 和 PSR-2 编码规范。任何新的代码贡献都必须附有单元测试（如果适用）。

附录一

swagger 注释文件 Feedback.php

swagger 注释文件 Summary.php

swagger 注释文件 Tags.php

网页效果图一

网页效果图二

网页效果图三

许可

MIT

tien / think-swagger

维护者

详细信息