Think PHP6+Swagger3

swagger是一个解决接口规范化、标准化、文档化的一个组件，既可以直接自动生成resutful接口文档又能进行功能测试的一个web服务。本文是think PHP6结合swagger3的一个记录过程。

composer安装ThinkPHP

一般安装最新稳定版本，不一定是最新版本

composer create-project topthink/think tp

运行测试

命令行执行命令

php think run

浏览器输入

http://localhost:8000/

或者更换端口

php think run -p 80

swagger-ui

gitclone

git clone https://github.com/swagger-api/swagger-ui.git

里面用到的是dist目录下的文件。复制swagger-ui下的dist文件夹到tp项目的public下，改不改名都行

修改swagger-initializer.js

例如生成swagger.json放在public目录下的话，就改成如下

http://localhost:8000/swagger.json

安装swagger-php

composer require zircote/swagger-php 3.*

生成swagger.json

一、命令行生成

在public目录下生成一个swagger.json文件

php ./vendor/bin/openapi E:\code\tp\app -o E:\code\tp\public\swagger.json

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

由于上面命令行每次修改文件都需要重新输入，所以可以添加下面的方法

二、快速更新文档（推荐）

路由文件

Route::get('swagger', 'index/swagger');

控制器

	public function swagger()
    {
        $openapi = \OpenApi\scan(root_path() . 'app');//你想要哪个文件夹下面的注释生成对应的API文档
        header('Content-Type: application/x-yaml');
        $jsonString = root_path() .'public/swagger.json';
        $res = file_put_contents($jsonString, $openapi->toJson());
        if ($res == true) {
            return redirect('http://localhost:8000/dist/index.html');
        }
    }

完整例子

namespace app\controller;

use app\BaseController;

/**
 * @OA\Info(title="thinkphp6接口文档", version="1.0.1")
 */

class Index extends BaseController
{
    /**
     * @OA\Get(path="/api/article",
     *   tags={"文章管理"},
     *   summary="文章列表",
     *   @OA\Parameter(name="token", in="header", description="token", @OA\Schema(type="string", default="123456")),
     *   @OA\Parameter(name="page", in="query", description="页码", @OA\Schema(type="int", default="1")),
     *   @OA\Parameter(name="limit", in="query", description="行数", @OA\Schema(type="int", default="10")),
     *   @OA\Response(response="200", description="The User")
     * )
     */
    public function index()
    {
                return '
 
:) 
 ThinkPHP V' . \think\facade\App::version() . '
14载初心不改 - 你值得信赖的PHP框架
[ V6.0 版本由 亿速云 独家赞助发布 ]
';
}
/**
* @OA\Post(path="/api/article",
* tags={"文章管理"},
* summary="新增文章",
* @OA\Parameter(name="token", in="header", description="token", @OA\Schema(type="string")),
* @OA\RequestBody(
* @OA\MediaType(
* mediaType="multipart/form-data",
* @OA\Schema(
* @OA\Property(description="文章名称", property="title", type="string", default="dd"),
* @OA\Property(description="文章内容", property="content", type="string"),
* required={"title", "content"})
* )
* ),
* @OA\Response(response="200", description="successful operation")
* )
*/
public function save()
{
//save业务代码
}
/**
* @OA\Get(path="/api/article/{id}",
* tags={"文章管理"},
* summary="文章详情",
* @OA\Parameter(name="token", in="header", description="token", @OA\Schema(type="string")),
* @OA\Parameter(name="id", in="path", description="文章id", @OA\Schema(type="int")),
* @OA\Response(response="200", description="The User")
* )
*/
public function read($id)
{
//read业务代码
}
/**
* @OA\Put(path="/api/article/{id}",
* tags={"文章管理"},
* summary="编辑文章",
* @OA\Parameter(name="token", in="header", description="token", @OA\Schema(type="string")),
* @OA\Parameter(name="id", in="path", description="文章id", @OA\Schema(type="int")),
* @OA\RequestBody(
* @OA\MediaType(
* mediaType="content-type/json",
* @OA\Schema(
* @OA\Property(description="文章名称", property="title", type="string"),
* @OA\Property(description="文章内容", property="content", type="string"),
* required={"title", "content"})
* )
* ),
* @OA\Response(response="200", description="successful operation")
* )
*/
public function update($id)
{
//update业务代码
}
/**
* @OA\Delete(path="/api/article/{id}",
* tags={"文章管理"},
* summary="删除文章",
* @OA\Parameter(name="token", in="header", description="token", @OA\Schema(type="string")),
* @OA\Parameter(name="id", in="path", description="文章id", @OA\Schema(type="int")),
* @OA\Response(response="200", description="The User")
* )
*/
public function delete($id)
{
//delete业务代码
}
}

浏览器输入http://localhost:8000/swagger