swagger在thinkphp6的使用方式

以下以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\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：參數在地址後傳遞如 test.com?id=1
3、path:參數在rest地址中如 test.com/user/1
4、cookie:參數在cookie中傳遞

Schema配置

1、type：指定字段類型
2、default：指定字段默認值

更多使用方式參考php項目中vendor中zircote\swagger-php目錄下的Examples文件
訪問http://dev.think.com/dist/既可使用swagger