swagger-php注释写法教程,实用例子

网上关于swagger-php的注释写法,资料较少。最全面的应该是 Laravel-China上如何编写基于 Swagger-PHP 的 API 文档

本篇文章记录一下遇到的坑。

文章中第1章2.5节,

required的值应该是true,不带引号。

如果是post请求,请求消息体中包含多个参数,并且修改了header内容。

header内容应该放到form内容之前。例子:

   /**
     * @SWG\Post(
      *     path="/mall/save",
      *     summary="保存采集的id",
      *     description="用户使用浏览器插件,将某个日期的流量id保存到服务器",
      *     tags={"Mall"},
      *     @SWG\Parameter(
      *          name="token",
      *          type="string",
      *          required=true,
      *          in="header",
      *          description="令牌"
      *     ),
      *     @SWG\Parameter(
      *          name="date",
      *          type="string",
      *          format="date",
      *          required=true,
      *          in="formData",
      *          default="2018-12-05",
      *          description="日期。格式为2018-12-05"
      *     ),
      *     @SWG\Parameter(
      *          name="mallId",
      *          type="string",
      *          required=true,
      *          in="formData",
      *          description="店铺id"
      *     ),44      *     @SWG\Response(
      *         response="200",
      *         description="状态码、提示消息",
      *         @SWG\Schema(
      *              required={"code","message"},
      *              @SWG\Property(
      *                  property="code",
      *                  type="integer",
     *                  format="int32",
      *                  description="状态码"
      *              ),
      *              @SWG\Property(
      *                  property="message",
      *                  type="string",
      *                  description="提示消息"
      *              ),
      *              @SWG\Property(
      *                  property="data",
      *                  type="string",
      *                  description="数据"
      *              )
      *          )
      *     )
      * )
     */

 返回复杂结果的例子:

/**
     * @SWG\Post(
     *     path="/mall/get",
     *     summary="获取所有采集的id",
     *     description="获取所有采集的id",
     *     tags={"Mall"},
     *     @SWG\Parameter(
     *          name="token",
     *          type="string",
     *          required=true,
     *          in="header",
     *          description="令牌"
     *     ),
     *     @SWG\Parameter(
     *          name="mallId",
     *          type="string",
     *          required=true,
     *          in="formData",
     *          default="123123",
     *          description="店铺id"
     *     ),
     *     @SWG\Response(
     *         response="200",
     *         description="状态码、提示消息",
     *         @SWG\Schema(
     *              required={"code","message"},
     *              @SWG\Property(
     *                  property="code",
     *                  type="integer",
     *                  format="int32",
     *                  description="状态码"
     *              ),
     *              @SWG\Property(
     *                  property="message",
     *                  type="string",
     *                  description="提示消息"
     *              ),
     *              @SWG\Property(
     *                  property="data",
     *                  type="array",
     *                  @SWG\Items(
     *                      @SWG\Property(
     *                          property="id",
     *                          type="integer",
     *                          description="流量记录id"
     *                      ),
     *                      @SWG\Property(
     *                          property="date",
     *                          type="string",
     *                          description="流量id所在的日期。例:2019-01-01"
     *                      ),
     *                      @SWG\Property(
     *                          property="nallIdNum",
     *                          type="integer",
     *                          description="id的数量"
     *                      )
     *                  )
     *              ),
     *          )
     *     )
     * )
     */

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值