thinkphp6+swagger-php配置管理接口文档
Posted
tags:
篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了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中加上
<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只能显示头部,无法显示接口详细信息
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 = OpenApiscan($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,如下代码:
/**
- @OASwagger(
- schemes={"http"},
- host="127.0.0.1:8806",
- basePath="/",
- @OAInfo(
- version="1.0.0",
- title="接口文档",
- description="Version: 1.0.0",
- @OAContact(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将会更灵活、功能更完整
案例:
<?php
use OpenApiAnnotations as OA;
/**
- @OAInfo(
- version="1.0",
- title="Example for response examples value"
- )
*//**
- @OAPost(
- path="/users",
- summary="Adds a new user",
- @OARequestBody(
- @OAMediaType(
- mediaType="application/json",
- @OASchema(
- @OAProperty(
- property="id",
- type="string"
- ),
- @OAProperty(
- property="name",
- type="string"
- ),
- example={"id": 10, "name": "Jessica Smith"}
- )
- )
- ),
- @OAResponse(
- response=200,
- description="OK"
- )
- )
*/
以上为post请求的例子,请区别与2.0的不同
<?php
namespace OpenApiLinkExample;
/**
MVC controller that handles "users/" urls.
/
class UsersController
{/**
- @OAGet(path="/2.0/users/{username}",
- operationId="getUserByName",
- @OAParameter(name="username",
- in="path",
- required=true,
- @OASchema(type="string")
- ),
- @OAResponse(response="200",
- description="The User",
- @OAJsonContent(ref="#/components/schemas/user"),
- @OALink(link="userRepositories", ref="#/components/links/UserRepositories")
- )
- )
*/
public function getUserByName($username)
{
}
}
以上为get请求的例子
详细可以参考下原文档(后期有时间我再逐一补充完善):
1、https://github.com/zircote/swagger-php
2、https://swagger.io/docs/specification/basic-structure/
以上是关于thinkphp6+swagger-php配置管理接口文档的主要内容,如果未能解决你的问题,请参考以下文章