swagger在项目中的使用（php）
2021-02-18 07:18
阅读：596
为什么要使用swagger:
- 利于代码与注释与api文档相同步
- 接口的文档在线自动生成
- 可以直接使用可视化api文档进行接口调试
- 直接生成api文档文件，便于保存以及之后统一管理
- 支持多种语言java，go，php都可以使用swagger生成api文档
首先需要安装以下一个东西：
1. PhpStorm 插件：
1. Swagger Plugin
2. PHP Annotation
==安装完成PhpStorm扩展后需要重启PhpStorm==
2. 安装swagger-php（yaml文件生成工具）
composer require zinco/swagger-php
安装完成之后，在php文件中写入注释
/**
* @OA\Info(title="My First API", version="0.1")
*/
/**
* @OA\Get(
* path="/api/resource.json",
* @OA\Response(response="200", description="An example resource")
* )
*/
在另一个文件或方法中写入如下代码：
require("vendor/autoload.php"); // 如果已经实现composer自动加载可将此行注释
$openapi = \OpenApi\scan(‘/path/to/project‘);// /path/to/project 为含有swagger注释文件的上层目录路径
header(‘Content-Type: application/x-yaml‘);
echo $openapi->toYaml();
访问该文件或方法即可获得swagger yaml文件
3. 安装swagger-ui（swagger-api页面文件）
composer require swagger-api/swagger-ui
将swagger-ui/dist目录复制到可访问的目录中，如public下
修改index.html中如下位置代码：
SwaggerUIBundle({
url: "http://local.homestead.com/api/swagger", // 需要将此路径改为上一个文件的地址
访问 地址/dist 即可查看api文档
4. swagger 注解格式示例：
/**
* @OA\Info(title="My First API", version="0.1")
*/
// 读取
/**
* @Get(
* path="/hello/{id}",
* @Parameter(
* name="id",
* in="path",
* required=true,
* description="123123",
* @Schema(type="integer")
* ),
* @Response(
* response=200,
* description="SUCCESS/成功",
* @MediaType(
* mediaType="application/json",
* @Schema(
* @Property(property="code", type="integer", format="int32", description="标识"),
* @Property(property="msg", type="string", format="int32", description="描述"),
* @Property(property="data",type="object",description="返回数据",
* @Property(property="no",type="string",description="版本号"),
* @Property(property="account",type="string",description="用户"),
* @Property(property="real_name",type="string",description="权限名称"),
* ),
* ),
* example={"code": 0,"msg": "success","data": {"no": "1.3","account": "admin","real_name": "god"}}
* )
* )
* )
*/
// 增加
/**
* @Post(
* path="/hello/file-upload",
* tags={"admin-member"},
* summary="Upload one user document",
* description="Upload one user document",
* @RequestBody(
* @MediaType(mediaType="application/x-www-form-urlencoded",
* @Schema(
* type="object",
* required={"file", "id", "type"},
* @Property(property="file", type="string", format="binary", description="user document file"),
* @Property(property="id", type="integer", description="user id"),
* @Property(property="type", type="string", enum={"verification_file","id_card_file","credit_card_file"})
* )
* )),
* @Response(
* response=200,
* description="successful operation"
* )
* )
*/
/**
* @Post(
* path="/hello/xx-yy",
* tags={"admin-sales-type"},
* summary="Store a newly created sales type item in storage",
* description="Store a newly created sales type item in storage",
* @RequestBody(required=true, @JsonContent(
* required={"sales_name", "handle_fee", "commission", "status", "visible", "keywords", "sales_name_abbr", "charge_full_domestic", "default", "tiers"},
* @Property(property="sales_name", type="string", description="sales name"),
* @Property(property="handle_fee", type="number", format="float", description="handle fee", example="15.00"),
* @Property(property="status", type="integer", enum={1, 0}),
* @Property(property="charge_full_domestic", type="integer", description="charge full domestic"),
* @Property(property="default", type="string", enum={1, 0}),
* @Property(property="tiers", type="array", description="tiers",
* @Items(
* @Property(property="type", type="string", enum={"flat", "basic", "subtract", "platform"}),
* @Property(property="from", type="integer", description="from", example="0")
* )
* ),
* )),
* @Response(
* response="200",
* description="successful operation"
* )
* )
*/
// 修改
/**
* @Patch(
* path="/admin/member/{id}",
* tags={"admin-member"},
* summary="get member info",
* description="get member info",
* @RequestBody(required=true, @JsonContent(
* @Property(property="name", type="string", description="user name"),
* @Property(property="display_currency", type="string", enum={"USD","JPY"})
* )),
* @Parameter(
* name="id", in="path", description="member id",
* required=true, @Schema(type="integer")),
* @Response(
* response=200,
* description="successful operation"
* )
* )
*/
// 删除
/**
* @Delete(
* path="/hello/delete/{id}",
* tags={"admin-member"},
* summary="Remove the specified resource from storage",
* description="Remove the specified resource from storage",
* @Parameter(
* name="id", in="path", description="member id",
* required=true, @Schema(type="integer")),
* @Response(
* response=200,
* description="successful operation"
* )
* )
*/
// 加密认证
/**
* @SecurityScheme(
* type="http",
* description="xxx sign",
* in="header",
* scheme="bearer"
* )
*/
设置公共头
/**
*@Server(url="http://local.publichomestead.com/hello",description="asdfasdasdf")
*/
还以一些语法会陆续进行补充
评论
亲，登录后才可以留言！