thinkphp6+swagger-php配置管理接口文檔

swagger2 升級到了3，並更名爲OpenAPI Spec，全部部分註解有一些變化，這裏以thinkphp6+swagger-php3.0來配置javascript

一、前端部分git或dowload一份swagger-ui到可以訪問到服務目錄中，如我這裏nginx配置指向到thinkphp6根目錄public中,因此download一份swagger-ui到該根目錄中，swagger-ui下載地址https://github.com/swagger-api/swagger-ui

找到dist目錄, 打開index.html把其中的url改爲本身到服務器url，這裏我以本地配置爲例：

php

若是想支持中文在index.html中加上html

<script src='lang/translator.js' type='text/javascript'>
</script><script src='lang/zh-cn.js' type='text/javascript'></script>
前端

原項目網頁地址是：http://127.0.0.1:8806, 如今接口前端ui地址是：http://127.0.0.1:8806/swagger-ui/dist/index.html, 此時由於沒有配置swagger.json只能顯示頭部，沒法顯示接口詳細信息java

二、安裝swagger-php後端，在thinkphp6框架的總目錄下面執行，composer安裝swagger-php插件。(最好使用composer管理插件,萬一composer沒法使用能夠嘗試手動安裝)

composer require zircote/swagger-phpnginx

注意此時安裝是使用最新版的3.0git

三、這裏經過swagger自定義對註解，而後由swagger-php來生成swagger.json的接口配置文件。生成方法：

命令行生成

$> php /usr/local/var/www/vendor/zircote/swagger-php/bin/openapi /usr/local/var/www/app/api/controller -o /usr/local/var/www/public/uploadsgithub

其中：
/usr/local/var/www/vendor/zircote/swagger-php/bin/openapi 爲swagger-php插件生成json文件的主命令
/usr/local/var/www/app/api/controller 爲接口目錄，該目錄會被主命令依次掃描生成對應json配置代碼
/usr/local/var/www/public/uploads 爲swagger.json存儲文件的目錄

thinkphp

經過控制器代碼自動生成swagger.json

public function apidoc(){
// $RootDir = $_SERVER['DOCUMENT_ROOT'];
json

$path ='../app/api/controller'; //你想要哪一個文件夾下面的註釋生成對應的API文檔
    $swagger = \OpenApi\scan($path);
    header('Content-Type: application/x-yaml');
    // var_dump($swagger);
    $swagger_json_path = './uploads/swagger.json';

    $res = file_put_contents($swagger_json_path,$swagger-&gt;toYaml());
    if ($res == true) {
        return redirect('http://127.0.0.1:8806/swagger-ui/dist/index.html');
    }
}

自動生成swagger.json後會自動跳轉到最開始配置到swagger-ui前端地址，咱們能夠嘗試在controller目錄下新建一個swagger.php，以下代碼：

/**

@OA\Swagger(

schemes={"http"},

host="127.0.0.1:8806",

basePath="/",

@OA\Info(

version="1.0.0",

title="接口文檔",

description="Version: 1.0.0",

@OA\Contact(name = "daydream", email = "heheiscool@163.com")

),
*/

注意swagger格式，這裏行前綴以*開頭，你們本身替換下(這裏編輯顯示有點小問題)
而後顯示如下就表明配置正常了：

四、OpenApi3.0(swagger3.0)的語法格式，建議直接參考案例比較快。這裏注意：

原來2.0的@SWG都被@OA替代
接口參數請求in的類型有：path、headers、cookies，沒有了query、formData等
formData被關鍵字requestBody替代，requestBody將會更靈活、功能更完整

案例：

<?php

use OpenApi\Annotations as OA;

/**

@OA\Info(

version="1.0",

title="Example for response examples value"

)
*/

/**

@OA\Post(

path="/users",

summary="Adds a new user",

@OA\RequestBody(

@OA\MediaType(

mediaType="application/json",

@OA\Schema(

@OA\Property(

property="id",

type="string"

),

@OA\Property(

property="name",

type="string"

),

example={"id": 10, "name": "Jessica Smith"}

)

)

),

@OA\Response(

response=200,

description="OK"

)

)
*/

以上爲post請求的例子，請區別與2.0的不一樣

<?php

namespace OpenApi\LinkExample;

/**

MVC controller that handles "users/" urls.
/
class UsersController
{

/**

@OA\Get(path="/2.0/users/{username}",

operationId="getUserByName",

@OA\Parameter(name="username",

in="path",

required=true,

@OA\Schema(type="string")

),

@OA\Response(response="200",

description="The User",

@OA\JsonContent(ref="#/components/schemas/user"),

@OA\Link(link="userRepositories", ref="#/components/links/UserRepositories")

)

)
*/
public function getUserByName($username)
{
}
}

以上爲get請求的例子
詳細能夠參考下原文檔（後期有時間我再逐一補充完善）：
一、https://github.com/zircote/swagger-php
二、https://swagger.io/docs/specification/basic-structure/