swagger2 升級到了3，并改名為OpenAPI Spec，所有部分注解有一些變化，這里以thinkphp6+swagger-php3.0來配置

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

找到dist目錄, 打開index.html把其中的url改成自己到服務器url，這里我以本地配置為例：

如果想支持中文在index.html中加上

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

composer require zircote/swagger-php

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

3、這里通過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/uploads

其中：

/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存儲文件的目錄

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

public function apidoc(){

// $RootDir = $_SERVER['DOCUMENT_ROOT'];

$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->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格式，這里行前綴以*開頭，大家自己替換下(這里編輯顯示有點小問題)

然后顯示以下就代表配置正常了：

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

原來2.0的@SWG都被@OA替代

接口參數請求in的類型有：path、headers、cookies，沒有了query、formData等

formData被關鍵字requestBody替代，requestBody將會更靈活、功能更完整

案例：

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的不同

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)

{

}

}

總結

以上是生活随笔為你收集整理的swagger的php配置,thinkphp6+swagger-php配置管理接口文档的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。