swagger的php配置,thinkphp6+swagger-php配置管理接口文档
swagger2 升級(jí)到了3，并改名為OpenAPI Spec，所有部分注解有一些變化，這里以thinkphp6+swagger-php3.0來(lái)配置
1、前端部分git或dowload一份swagger-ui到能夠訪問(wèn)到服務(wù)目錄中，如我這里nginx配置指向到thinkphp6根目錄public中,所以download一份swagger-ui到該根目錄中，swagger-ui下載地址https://github.com/swagger-api/swagger-ui
找到dist目錄, 打開(kāi)index.html把其中的url改成自己到服務(wù)器url，這里我以本地配置為例：
如果想支持中文在index.html中加上
2、安裝swagger-php后端，在thinkphp6框架的總目錄下面執(zhí)行，composer安裝swagger-php插件。(最好使用composer管理插件,萬(wàn)一composer無(wú)法使用可以嘗試手動(dòng)安裝)
composer require zircote/swagger-php
注意此時(shí)安裝是使用最新版的3.0
3、這里通過(guò)swagger自定義對(duì)注解，然后由swagger-php來(lái)生成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 為接口目錄，該目錄會(huì)被主命令依次掃描生成對(duì)應(yīng)json配置代碼
/usr/local/var/www/public/uploads為swagger.json存儲(chǔ)文件的目錄
通過(guò)控制器代碼自動(dòng)生成swagger.json
public function apidoc(){
// $RootDir = $_SERVER['DOCUMENT_ROOT'];
$path ='../app/api/controller'; //你想要哪個(gè)文件夾下面的注釋生成對(duì)應(yīng)的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');
}
}
自動(dòng)生成swagger.json后會(huì)自動(dòng)跳轉(zhuǎn)到最開(kāi)始配置到swagger-ui前端地址，我們可以嘗試在controller目錄下新建一個(gè)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格式，這里行前綴以*開(kāi)頭，大家自己替換下(這里編輯顯示有點(diǎn)小問(wèn)題)
然后顯示以下就代表配置正常了：
4、OpenApi3.0(swagger3.0)的語(yǔ)法格式，建議直接參考案例比較快。這里注意：
原來(lái)2.0的@SWG都被@OA替代
接口參數(shù)請(qǐng)求in的類型有：path、headers、cookies，沒(méi)有了query、formData等
formData被關(guān)鍵字requestBody替代，requestBody將會(huì)更靈活、功能更完整
案例：
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請(qǐng)求的例子，請(qǐng)區(qū)別與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)
{
}
}
總結(jié)
以上是生活随笔為你收集整理的swagger的php配置,thinkphp6+swagger-php配置管理接口文档的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。
- 上一篇： php下载文件压缩包已经损坏或未知格式,
- 下一篇： php redis mset,MSET命