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的数量"
     *                      )
     *                  )
     *              ),
     *          )
     *     )
     * )
     */