swagger.php
用于生成swagger文件
<?php
namespace app\index\controller;
/**
* @SWG\Swagger (
* schemes={"https","http"},
* host="www.tp.cn",
* basePath="/",
* @SWG\SecurityScheme(securityDefinition="apikey",type="apiKey",name="token",in="header"),
* @SWG\Info (
* title="API文档",
* version="版本0.1",
* description="本文档仅限于测试",
* termsOfService="服务网址",
* @SWG\Contact(
* name="张先生",
* url="www.kevlin.com",
* email="kevlinzhang.china@gmail.com"
*
* ),
* @Swg\License(
* name="服务名称-异享律师",
* url="http://www.yixianglife.com"
* )
* ),
* @SWG\ExternalDocumentation(
* description = "Find out more about my website",
* url = "http://www.google.com"
* )
*
*
* )
*/
class Swagger
{
public function index()
{
// echo __DIR__;
// $swagger = \Swagger\scan("/www/wwwroot/default/thinkphp/application/index");
$swagger = \Swagger\scan("/www/wwwroot/default/thinkphp/application/index");
$swagger->saveAs('./swagger.json');
echo "swagger.json保存成功".rand(1,100);
}
}
Controller\Test.php
测试demo
<?php
namespace app\index\controller;
class Test
{
/**
* @SWG\Post (
* path = "/index/test/index",
* tags = {"后台管理"},
* summary = "更新用户信息",
* security={{"apikey"={}}},
* consumes={"application/json","application/xml"},
* produces={"application/json","application/xml"},
* description="用户的更新逻辑,记得一定要带`token`",
* @SWG\Parameter (name="id",type="integer",in="formData",description="商品的id",required=true),
* @SWG\Parameter (name="picture",type="file",in="formData",description="商品图片",required=false),
* @SWG\Parameter (
* in="body",
* required=true,
* name="bodyName",
* description="body description",
* @SWG\Schema(
* @SWG\Property (
* property="username",
* type="string",
* example="kevlin"
* ),
* @SWG\Property (
* property="password",
* type="string",
* readOnly=true
* )
* )
* ),
* @SWG\Response(response=200,description="请求成功",
* @SWG\Schema(
* @SWG\Property (
* property="code",
* type="number",
* example=10001
* ),
* @SWG\Property (
* property="msg",
* type="string",
* example="返回成功"
* ),
* @SWG\Property (
* property="data",
* type="object",
* example={"username"="root","password"="111111"}
* )
*
* )
* ),
* @SWG\Response(response=201,description="请求失败")
* )
*/
public function index()
{
}
/**
* @SWG\Get (
* path = "/index/test/add",
* tags = {"接口标签,可以是多个;设置多个相同的tags值,swagger会自动进行逻辑分组"},
* summary = "接口简介",
* description = "接口描述,支持`markdown`语法",
* operationId = "操作的id,需要唯一",
* security={{"apikey"={}}},
* consumes={"application/json","application/xml"},
* produces={"application/json"},
* @SWG\Parameter (name="id",type="integer",in="formData",description="商品的id",required=true),
* @SWG\Response(response=200,description="请求成功",@SWG\Schema(ref="#definitions/TestModel")),
* @SWG\Response(response=201,description="请求失败")
* )
*/
public function add()
{
}
}
Model\Test.php
定义模型(抽取重复定义的内容)
<?php
namespace app\index\model;
/**
* @SWG\Definition (definition="TestModel")
*/
class Test
{
/**
* @SWG\Property (example=100001)
* @var number
*/
protected $code;
/**
* @SWG\Property (example="ok")
* @var string
*/
protected $msg;
/**
* @SWG\Property (example={"token":"xxxxxxxx"})
* @var object
*/
protected $data;
}
需要注意的是参数items
和 collectionFormat
只有参数type=“array”才使用
当参数 in
选择“body”时必须定义@SWG\Schema()
或schema
,通过@SWG\Schema()
自定义一个 JSON
Definition请求类型
编写 API 文档时经常会遇到一些 API 的内容是重复的,抽取可以重新定义的内容,定义模型,使用definition
来简化我们的文档。
使用@SWG\Property()
参数来设置
参数 | 含义 |
---|---|
property | 名称 |
type | 类型,可以设置值为number,string,integer,boolean,array,object |
example | 设置默认值 |
readOnly | 属性声明 |
参数
readOnly
如果设置为true,这意味着它只作为响应的一部分发送,不能作为请求的一部分发送,默认false
Schema请求类型
参数 | 含义 |
---|---|
ref | 允许此路径的外部定义 |
example | 设置一个自定义对象 |
discriminator | 添加多个自定义的ref的支持 |
例:
/**
* @SWG\Schema(example={"username"="username","password"="password"})
*/
* @OA\RequestBody(
* required=true,
* description="匹配列",
* @OA\MediaType(
* mediaType="multipart/form-data",
* @OA\Schema(
* @OA\Property(property="id", type="string", example="1"),
* @OA\Property(property="qqcsv",type="file",format="string",description="文件")
* )
* )
*
* )
参考链接:
入门https://blog.csdn.net/meihuasheng/article/details/118405254
看云:https://www.kancloud.cn/chengguang/swagger-php
我爱学习网:https://www.5axxw.com/wiki/topic/galhwk
原理:使用zircote读取注释,(使用命令行php ./vendor/zircote/swagger-php/bin/swagger ./vendor/webpower/rest-api/ -o ./public/
)生成swagger.json文件(或者yaml文件);然后访问自定义的swagger.php文件(作用:swagger.json生成index.html到swagger-ui的目录中);访问的接口文档就是swagger-ui的界面