swagger 模板

原文链接：
https://blog.csdn.net/wang78699425/article/details/80572192

官方文档地址：
https://swagger.io/docs/specification/2-0/describing-parameters/
相关资料：
https://legacy.gitbook.com/book/huangwenchao/swagger/details
https://laravel-china.org/index.php/topics/7430/how-to-write-api-documents-based-on-swagger-php

Swagger配置

/**
 * 公共配置
 * @SWG\Swagger(
 *     basePath="/v1",
 *     schemes={"http", "https"},
 *     @SWG\Info(
 *         version="1.0.0",
 *         title="admin api"
 *     )
 * )
 */

请求数据模板

GET请求列表

/**
     * @SWG\Get(
     *   path="/goods/goods-list",
     *   tags={"商品"},
     *   summary="商品列表",
     *   @SWG\Parameter(
     *        in = "query",
     *        name = "goods_name",
     *        description = "商品名称",
     *        required = false,
     *        type = "string"
     *   ),
     *   @SWG\Parameter(
     *        in = "query",
     *        name = "min_shop_price",
     *        description = "商品最小价格",
     *        required = false,
     *        type = "number"
     *   ),
     *   @SWG\Parameter(
     *        in = "query",
     *        name = "max_shop_price",
     *        description = "商品最大价格",
     *        required = false,
     *        type = "number"
     *   ),
     *   @SWG\Parameter(
     *        in = "query",
     *        name = "goods_sn",
     *        description = "商品编号",
     *        required = false,
     *        type = "string"
     *   ),
     *   @SWG\Parameter(
     *        in = "query",
     *        name = "brand_id",
     *        description = "品牌id",
     *        required = false,
     *        type = "integer"
     *   ),
     *   @SWG\Parameter(
     *        in = "query",
     *        name = "goods_type",
     *        description = "商品类型  1：商品 2：套餐 3：积分商品",
     *        required = false,
     *        type = "string"
     *   ),
     *   @SWG\Parameter(
     *        in = "query",
     *        name = "status",
     *        description = "商品状态 空或0获取所有商品  1：在售  2：售罄 3：下架 4：在售+售罄",
     *        required = false,
     *        type = "string",
     *        enum={1, 2, 3, 4}
     *   ),
     *   @SWG\Parameter(
     *        in = "query",
     *        name = "cat_id",
     *        description = "商品分类id，可以是一二三级分类id，可以是数组（多个）或者数字",
     *        required = false,
     *        type = "integer"
     *   ),
     *   @SWG\Parameter(
     *        in = "query",
     *        name = "filter_cat_id",
     *        description = "需要进行过滤的商品分类id，可以是一二三级分类id，可以是数组（多个）或者数字",
     *        required = false,
     *        type = "integer"
     *   ),
     *   @SWG\Parameter(
     *        in = "query",
     *        name = "sort",
     *        description = "排序，依次是 库存排序 售价排序 销量排序 下单量  带'-'号的为倒序，反之为升序",
     *        required = false,
     *        type = "string",
     *        enum={"goods_number", "-goods_number", "shop_price", "-shop_price", "sales_volume", "-sales_volume"}
     *   ),
     *   @SWG\Parameter(
     *        in = "query",
     *        name = "get_good_evaluate",
     *        description = "需要获取好评量 0：不获取 1：获取",
     *        required = false,
     *        type = "integer",
     *        enum={0, 1}
     *   ),
     *   @SWG\Parameter(
     *        in = "query",
     *        name = "get_collect_num",
     *        description = "需要获取收藏数 0：不获取 1：获取",
     *        required = false,
     *        type = "integer",
     *        enum={0, 1}
     *   ),
     *   @SWG\Response(
     *     response="2000",
     *     description="获取商品列表",
     *     @SWG\Schema(ref="#/definitions/goodsTmp")
     *   )
     * )
     */

返回数据模板

定义块：

/**
 * 定义块，一维数组
 * @SWG\Definition(
 *     definition="goodsTmp",
 *     type="object",
 *     required={"goods_id"},
 *     @SWG\Property(
 *         property="goods_id",
 *         type="integer",
 *         description="商品id"
 *     ),
 *     @SWG\Property(
 *         property="cat_id",
 *         type="string",
 *         description="分类id，最多三级，按数组下标排级别"
 *     ),
 *     @SWG\Property(
 *         property="catName",
 *         type="string",
 *         description="商品分类层级名称，如：一级分类 > 二级分类 > 三级分类"
 *     )
 * )
 */

块与块组合

/**
 * 块与块组合
 * data 这样定义将一维数组组装成二维数组，pager这样定义是一维数组，再降两个数组合并
 * @SWG\Definition(
 *     definition="GoodsIndexListTmp",
 *     @SWG\Property(
 *         property="data",
 *         type="array",
 *         @SWG\Items(ref="#/definitions/goodsTmp"),
 *     ),
 *     @SWG\Property(
 *         property="pager",
 *         ref="#/definitions/Pager"
 *     )
 * )
 */

一维数组中添加字段后组合成二维数组

/**
 * @SWG\Definition(
 *     definition="IntegralGoodsIndexListTmp",
 *     @SWG\Property(
 *         property="data",
 *         type="array",
 *         @SWG\Items(
 *              allOf={
 *                  @SWG\Schema(ref="#/definitions/goodsTmp"),
 *                  @SWG\Schema(
 *                      @SWG\Property(
 *                          property="money",
 *                          type="integer",
 *                          description="兑换所需金额"
 *                      ),
 *                      @SWG\Property(
 *                          property="integral",
 *                          type="integer",
 *                          description="兑换所需积分"
 *                      ),
 *                      @SWG\Property(
 *                          property="some_day_total_exchange",
 *                          type="integer",
 *                          description="30天兑换量"
 *                      )
 *                  )
 *              }
 *          ),
 *     )
 * )
 */