原文链接:
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天兑换量"
* )
* )
* }
* ),
* )
* )
*/