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/