yii2 使用 zircote/swagger-php 進行swagger 搭建

網站上關於中文介紹的博客許多東西千篇一律，而且講的很多都浪費了我大量的時間。

然后就准備咬咬牙看看英語文檔：

https://packagist.org/packages/zircote/swagger-php

進行網站進行搭建，使用的是yii2 2.0.12

 

首先記得要處理跨域的問題，因為不同域名下調用post需要進行兩次握手， option 之后再 post，入口處添加

header("Access-Control-Allow-Origin:*");
header("Access-Control-Allow-Headers:content-type");
header("Access-Control-Request-Method:GET,POST");
if(strtoupper($_SERVER['REQUEST_METHOD'])== 'OPTIONS'){
    exit;
}

使用composer 進行安裝

composer require zircote/swagger-php

然后進行下載swagger-ui 這個主要進行一個swagger調試的客戶端，沒有進行后端的交互，他主要是通過一個json進行初始化工作

https://github.com/swagger-api/swagger-ui

 

然后對這個里面的dist/index.html進行修改json文件的引用，我是將這個客戶端放到一個獨立的域名下，然后在yii中寫入一個方法生成一個json

define('API_HOST',(YII_ENV === 'dev')?'new.rprise.wd.com':'test.com');
$b2broot = Yii::getAlias('@rprise');
$swagger = \Swagger\scan($b2broot);
echo $swagger;exit;

然后將dist/index.html 文件指向這個文件路由

// Build a system
const ui = SwaggerUIBundle({
  url: "http://new.rprise.wd.com/user/genswg",　　　　//修改這個位置
  dom_id: '#swagger-ui',
  deepLinking: true,


為了避免誤導大家，還是不多說了，最后還是希望大家還是多看看官方文檔

　　https://github.com/zircote/swagger-php/blob/HEAD/docs/Getting-started.md　　//這里編寫了代碼的注釋規范

 

　　看到一愣一愣的時候看看這個

　　https://bfanger.nl/swagger-explained/#schemaObject

 

一開始進行搭建代碼生成可能會報錯

比如

@SWG/info not fount 之類是因為沒寫注釋，總之耐心，相信官網文檔，有問題留言一下討論

最后附上一部分代碼，對着案例敲就好了

<?php
namespace rprise\controllers;
use yii\rest\ActiveController;
use rprise\models\ApiLoginForm;
use Swagger;
use rprise\models\ApiSignupForm;
use yii;

/**
 * @SWG\Swagger(
 *   schemes={"http"},
 *   host=API_HOST,
 *   produces={"application/json","application/xml"},
 *   consumes = {"application/json"},
 *   @SWG\Info(
 *     title="金融微店企業版",
 *     version="1.0.0",
 *     license={"name"="author：zhijie"}
 *   )
 * )
 * @SWG\Tag(
 *   name="user",
 *   description="用戶中心模塊",
 *   @SWG\ExternalDocumentation(
 *     description="Find out more about our store",
 *     url="http://swagger.io"
 *   )
 * )
 * @SWG\Definition(
 *     definition="Login",
 *      @SWG\Property(
 *        property="mobile_phone",
 *        description="手機號碼",
 *        type="string",
 *        example="15767952761"
 *      ),
 *      @SWG\Property(
 *         property="password",
 *         description="用戶密碼",
 *         type="string",
 *         example="zhijie9417"
 *      )
 *   ),
 */
class UserController extends ActiveController
{
    public $modelClass = 'rprise\models\user';

    public function actionGenswg()
    {
        define('API_HOST',(YII_ENV === 'dev')?'new.rprise.wd.com':'test.com');
        $b2broot = Yii::getAlias('@rprise');
        $swagger = Swagger\scan($b2broot);
        echo $swagger;exit;
    }
    /**
     * @SWG\Post(path="/user/login",
     *     tags={"user"},
     *     summary="用戶登錄",
     *     description="返回 access_token",
     *     @SWG\Parameter(
     *        in = "body",
     *        name = "mobile_phone & password",
     *        description = "手機號碼 && 密碼",
     *        required = true,
     *        type = "string",
     *        @SWG\Schema(ref="#/definitions/Login"),
     *     ),
     *     @SWG\Response(
     *         response = 200,
     *         description = " success"
     *     )
     * )
     *
     */
    public function actionLogin()
    {
    }

    public function actionSignup()
    {
    }



}