Think PHP6+Swagger3

news2024/11/23 23:54:11

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

修改rul
例如生成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');
        }
    }

完整例子

<?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业务代码
    }
}