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

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

 

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

文章中第1章2.5节，

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

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

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

 1     /**
 2      * @SWG\Post(
 3      *     path="/mall/save",
 4      *     summary="保存采集的id",
 5      *     description="用户使用浏览器插件，将某个日期的流量id保存到服务器",
 6      *     tags={"Mall"},
 7      *     @SWG\Parameter(
 8      *          name="token",
 9      *          type="string",
10      *          required=true,
11      *          in="header",
12      *          description="令牌"
13      *     ),
14      *     @SWG\Parameter(
15      *          name="date",
16      *          type="string",
17      *          format="date",
18      *          required=true,
19      *          in="formData",
20      *          default="2018-12-05",
21      *          description="日期。格式为2018-12-05"
22      *     ),
23      *     @SWG\Parameter(
24      *          name="mallId",
25      *          type="string",
26      *          required=true,
27      *          in="formData",
28      *          description="店铺id"
29      *     ),44      *     @SWG\Response(
45      *         response="200",
46      *         description="状态码、提示消息",
47      *         @SWG\Schema(
48      *              required={"code","message"},
49      *              @SWG\Property(
50      *                  property="code",
51      *                  type="integer",
52      *                  format="int32",
53      *                  description="状态码"
54      *              ),
55      *              @SWG\Property(
56      *                  property="message",
57      *                  type="string",
58      *                  description="提示消息"
59      *              ),
60      *              @SWG\Property(
61      *                  property="data",
62      *                  type="string",
63      *                  description="数据"
64      *              )
65      *          )
66      *     )
67      * )
68      */

 

 

 返回复杂结果的例子：

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

 

posted @ 2019-01-16 14:48  长空5  阅读(3069)  评论(1)  编辑  收藏  举报