Swagger3/thinkphp6教程

Swagger-PHP v3.x/thinkphp6教程

网上搜了很多关于swagger-PHP的教程,要么就是写的很乱,我完全看不懂,要么就是版本太旧,所以决定自己摸索一遍,顺便写一篇教程,日后好记!!!

准备工作

(要有一点PHP基础,起码要能搭建PHP环境,让PHP程序跑起来):

1. 安装Composer,windows下载,如果遇到任何问题或者想更深入地学习 Composer，请参考Composer 文档（英文文档，中文文档）
2. 安装thinkphp6,确保能正常运行(不懂得可看 ThinkPHP6.0完全开发手册)

安装zircote/swagger-php依赖

在thinkphp6项目根目录下运行命令:

composer require zircote/swagger-php

运行完成如下,在vendor目录下出现zircote文件夹:

编写swagger

自学能力强的可以自己看文档Swagger-PHP v3.x,这里我就直接略过文档了

在route文件夹下app.php:

<?php
use think\facade\Route;

Route::get('think', function () {
    return 'hello,ThinkPHP6!';
});

Route::get('hello/:name', 'index/hello');

//下面是新加的
Route::get('/swagger', function() {
    $openapi = OpenApi\scan(root_path().'app');
    //$openapi = OpenApi\scan('../app');//当然,你也可以用这种相对路径的写法,但是我建议还是用上面,避免更换route路径后出现问题
    header('Content-Type: application/json');
    echo $openapi->toJson();
});

然后再app文件夹下controller\Index.php:

<?php
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 '<style type="text/css">*{ padding: 0; margin: 0; } div{ padding: 4px 48px;} a{color:#2E5CD5;cursor: pointer;text-decoration: none} a:hover{text-decoration:underline; } body{ background: #fff; font-family: "Century Gothic","Microsoft yahei"; color: #333;font-size:18px;} h1{ font-size: 100px; font-weight: normal; margin-bottom: 12px; } p{ line-height: 1.6em; font-size: 42px }</style><div style="padding: 24px 48px;"> <h1>:) </h1><p> ThinkPHP V' . \think\facade\App::version() . '<br/><span style="font-size:30px;">14载初心不改 - 你值得信赖的PHP框架</span></p><span style="font-size:25px;">[ V6.0 版本由 <a href="https://www.yisu.com/" target="yisu">亿速云</a> 独家赞助发布 ]</span></div><script type="text/javascript" src="https://tajs.qq.com/stats?sId=64890268" charset="UTF-8"></script><script type="text/javascript" src="https://e.topthink.com/Public/static/client.js"></script><think id="ee9b1aa918103c4fc"></think>';

    }

    /**
     * @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业务代码
    }
}

接下来是查看效果:

根目录下执行:

php think run

在浏览器输入 http://127.0.0.1:8000/swagger,出现如下json格式的字符串,就算成功了

使用Swagger UI自动生成接口文档

下载前端代码:https://github.com/swagger-api/swagger-ui

下载好之后找到dist目录下的inedx.html文件,如下图

双击打开index.html文件,浏览器如下显示,在这个页面你就可以调试接口了:

其他

导出静态openapi.json文件(在根目录下可以找到openapi.json文件):

./vendor/bin/openapi --output openapi.json ./app

具体用法请 查看链接
效果: