php使用swagger來實現api文檔展現和測試

安裝node

cd /usr/local/
wget https://nodejs.org/dist/v10.15.0/node-v10.15.0-linux-x64.tar.xz
yum -y install xz
xz -d node-v10.15.0-linux-x64.tar.xz
tar -xvf node-v10.15.0-linux-x64.tar
mv node-v10.15.0-linux-x64 node
ln -s /usr/local/node/bin/node /usr/bin/node
ln -s /usr/local/node/bin/npm /usr/bin/npm

安裝swagger-gui

npm install -g http-server
ln -s /usr/local/node/bin/http-server /usr/bin/http-server
yum -y install git
git clone https://github.com/swagger-api/swagger-ui
cd swagger-ui
http-server// -p 80(默認端口8080)
http://127.0.0.1:8080

安裝swagger-php

{
  "require": {
    "zircote/swagger-php": "^3.0.1"
  },
  "autoload": {
  },
  "repositories": {
    "packagist": {
      "type": "composer",
      "url": "https://packagist.phpcomposer.com"
    }
  }
}

composer install

寫php註解

<?php

/**
 * @OA\OpenApi(
 *    @OA\Info(
 *      version="1.0.0",
 *      title="api文檔",
 *      description="api文檔"
 *    ),
 *    @OA\Server(
 *       description="測試環境",
 *       url="127.0.0.1",
 *   ),
 *    @OA\Server(
 *       description="正式環境",
 *       url="10.0.0.1",
 *   )
 * )
 *
 * @OA\Schema(
 *     schema="news",
 *     type="object",
 *     required={"title","content"},
 *     @OA\Property(
 *         property="id",
 *         type="integer",
 *         description="編號"
 *     ),
 *     @OA\Property(
 *         property="title",
 *         type="string",
 *         description="標題"
 *     ),
 *     @OA\Property(
 *         property="content",
 *         type="string",
 *         description="正文"
 *     ),
 *     @OA\Property(
 *         property="cover",
 *         type="string",
 *         description="配圖地址"
 *     ),
 *     @OA\Property(
 *         property="time",
 *         type="string",
 *         description="發佈時間"
 *     )
 * )
 *
 * @OA\Schema(
 *     schema="Paging",
 *     @OA\Property(
 *          property="page",
 *          type="integer",
 *          description="頁碼",
 *          format="int32",
 *          default="1"
 *     ),
 *     @OA\Property(
 *          property="limit",
 *          type="integer",
 *          description="每頁個數",
 *          format="int32",
 *          minimum="0",
 *          exclusiveMinimum=true,
 *          maximum="100",
 *          exclusiveMaximum=false
 *     )
 * )
 */
class NewsController
{

    /**
     * @OA\Get(
     *     path="/news/{type}",
     *     summary="獲取資訊",
     *     description="返回包含已發佈的資訊列表",
     *     @OA\Parameter(
     *          name="type",
     *          in="path",
     *          required=true,
     *          description="類型",
     *          @OA\Schema(
     *             type="string",
     *             enum={"entertainment","Sports"}
     *         )
     *     ),
     *     @OA\Parameter(
     *          name="page",
     *          in="query",
     *          @OA\Schema(
     *             @OA\Items(ref="#/components/schemas/Paging")
     *         )
     *     ),
     *     @OA\Response(
     *         response=200,
     *         description="一個資訊列表",
     *         @OA\Schema(
     *             type="array",
     *             @OA\Items(ref="#/components/schemas/news")
     *         ),
     *     )
     * )
     */
    public function indexAction()
    {
        echo 'a';
    }
}

生成文檔

./vendor/bin/openapi -o api.yml -e vendor --format yaml --debug .