swagger3在php项目中的使用

以下以thinkphp6框架及dev.think.com项目域名进行示范：

下载swagger-ui

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

复制swagger-ui目录下dist文件到php项目根目录

如：thinkphp6的public目录下

打开php项目安装swagger-php拓展

composer require zircote/swagger-php

编写文档接口

<?php
use think\facade\Route;

Route::get('/swagger', function() {
   $openapi = \OpenApi\scan('../app');

    header('Content-Type: application/json');
    echo $openapi->toJson();
});

编辑dist目录下index.html文件，修改url地址为文档路由地址

window.onload = function() {
  // Begin Swagger UI call region
  const ui = SwaggerUIBundle({
    url: "http://dev.think.com/swagger",//路由地址
    dom_id: '#swagger-ui',
    deepLinking: true,
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: "StandaloneLayout"
  })

注解格式参考

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

/**
    * @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()
{
       $limit = $this->request->param('limit/d', 10);
       $data = ArticleModel::paginate($limit);
       return $this->jsonReturn(200, 'success', $data);
}

   /**
    * @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()
   {
       $param = $this->request->post();
       $rule = [
           'title' => 'require',
           'content' => 'require'
       ];

       $param = array_intersect_key($param, $rule);
       try {
           $this->validate($param, $rule);
       } catch (ValidateException $e) {
           return $this->jsonReturn(412, $e->getError());
       }

       ArticleModel::create([
           'title' => $param['title'],
           'content' => $param['content'],
           'created_at' => date('Y-m-d H:i:s')
       ]);

       return $this->jsonReturn();
   }

   /**
    * @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)
   {
       $data = ArticleModel::whereId($id)->find();
       return $this->jsonReturn(200, 'success', $data);
   }

   /**
    * @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)
   {
       $param = $this->request->put();
       $rule = [
           'title' => 'require',
           'content' => 'require'
       ];

       $param = array_intersect_key($param, $rule);

       try {
           $this->validate($param, $rule);
       } catch (ValidateException $e) {
           return $this->jsonReturn(412, $e->getError());
       }

       ArticleModel::whereId($id)->update([
           'title' => $param['title'],
           'content' => $param['content'],
           'updated_at' => date('Y-m-d H:i:s')
       ]);

       return $this->jsonReturn();
   }

   /**
    * @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)
   {
       ArticleModel::destroy($id);
       return $this->jsonReturn();
   }

PUT、POST请求方式的注解格式不一样

Paramter参数的in参数

1、header:参数在header头中传递
2、query：参数在地址后传递如 http://dev.think.com?id=1
3、path:参数在rest地址中如 http://dev.think.com/user/1
4、cookie:参数在cookie中传递

Schema配置

1、type：指定字段类型
2、default：指定字段默认值

更多使用方式参考php项目中vendor中zircote\swagger-php目录下的Examples文件
访问http://dev.think.com/dist/既可使用swagger