php与swagger3自定义,thinkphp6+swagger-php配置管理接口文档
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 = "[email protected]")
),
*/
注意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)
{
}
}