swagger的php配置,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

54029ff97c5e0af50ff5ae04cf88cc6e.png

找到dist目录, 打开index.html把其中的url改成自己到服务器url,这里我以本地配置为例:

6e60f883078be845c7ae5e014a2019cc.png

如果想支持中文在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格式,这里行前缀以*开头,大家自己替换下(这里编辑显示有点小问题)

然后显示以下就代表配置正常了:

2161aabe89facce8caa873bc7b7de726.png

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)

{

}

}

  • 0
    点赞
  • 1
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
Swagger-UI在线接口文档的优点包括以下几个方面: 1. 支持接口文档导出:Swagger-UI可以将接口文档以PDF、Word和Markdown等格式导出,方便开发者进行离线查阅和分享。[2] 2. 多种方式使用:Swagger-UI可以与其他工具同时使用,比如springfox-swagger-ui,可以根据项目需求选择最适合的方式。[2] 3. 友好的界面:相比于springfox-swagger-ui,Swagger-UI的界面更加友好,排版结构更加清晰,使得接口文档更易于理解和使用。[2] 4. 搜索功能:Swagger-UI支持接口内容的搜索,可以快速定位到需要查找的接口,提高了开发效率。[2] 5. 接口版本管理:Swagger-UI可以对接口进行版本管理,方便开发者对接口进行更新和维护。[2] 6. 国际化支持:Swagger-UI支持多语言界面,可以根据用户的语言偏好进行界面显示。[2] 7. 自定义文档:Swagger-UI支持开发者对接口文档进行自定义,可以根据项目需求添加额外的信息和说明。[2] 8. 生产环境屏蔽:Swagger-UI支持在生产环境中屏蔽Swagger的所有资源接口,保护接口文档的安全性。[2] 9. 接口权限控制:Swagger-UI可以设置在线接口文档的权限控制,限制不同用户对接口文档的访问权限。[2] 综上所述,Swagger-UI在线接口文档具有导出、多种使用方式、友好界面、搜索功能、版本管理、国际化支持、自定义文档、生产环境屏蔽和权限控制等优点。

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值