swagger在项目中的使用（php）

Posted 2021-02-18 xiami2046

为什么要使用swagger:

1. 利于代码与注释与api文档相同步
2. 接口的文档在线自动生成
3. 可以直接使用可视化api文档进行接口调试
4. 直接生成api文档文件，便于保存以及之后统一管理
5. 支持多种语言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文件中写入注释

/**
 * @OAInfo(title="My First API", version="0.1")
 */

/**
 * @OAGet(
 *     path="/api/resource.json",
 *     @OAResponse(response="200", description="An example resource")
 * )
 */

在另一个文件或方法中写入如下代码：

require("vendor/autoload.php"); // 如果已经实现composer自动加载可将此行注释
$openapi = OpenApiscan(‘/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 注解格式示例：

/**
 * @OAInfo(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")
 */

还以一些语法会陆续进行补充

作者：ReallyWang
链接：https://www.jianshu.com/p/599fa5f2b915
来源：简书
著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。