在PHPer中，很多人聽(tīng)說(shuō)過(guò)Swagger，部分人知道Swagger是用來(lái)做API文檔的，然而只有少數(shù)人真正知道怎么正確使用Swagger，因?yàn)?code>PHP界和Swagger相關(guān)的資料實(shí)在是太少了。所以鄙人斗膽一試，希望能以本文幫助到大家了解Swagger，從此告別成天用Word、Markdown折騰API文檔的日子。

什么是Swagger

Swagger is a simple yet powerful representation of your RESTful API. With the largest ecosystem of API tooling on the planet, thousands of developers are supporting Swagger in almost every modern programming language and deployment environment. With a Swagger-enabled API, you get interactive documentation, client SDK generation and discoverability.

Swagger是一種簡(jiǎn)單、強(qiáng)大的RESTful API表現(xiàn)形式。
其擁有地球上最大的API工具生態(tài)環(huán)境，無(wú)數(shù)程序員在幾乎所有主流語(yǔ)言和開(kāi)發(fā)環(huán)境中添加了對(duì)Swagger的支持。
只要你的API添加對(duì)Swagger的支持，你就等于擁有了可交互的API文檔，SDK代碼生成以及外部使用友好的API。

• Swagger.io首頁(yè)

寫了這么一堆貌似很屌的話，所以……Swagger到底是個(gè)啥？是一套代碼還是一個(gè)軟件呢？

其實(shí)和官網(wǎng)高度概括的描述一樣，Swagger是一種通用的、和編程語(yǔ)言無(wú)關(guān)的API的描述規(guī)范。只要開(kāi)發(fā)者在自己的API之上添加符合Swagger規(guī)范的描述，就能利用上Swagger豐富的生態(tài)，找到符合自己開(kāi)發(fā)語(yǔ)言的工具去做很多事：比如最常用的生成API文檔，或者生成返回假數(shù)據(jù)的服務(wù)端基礎(chǔ)代碼等等。

人類的文字便是一種規(guī)范，人理解了文字的規(guī)范就可以進(jìn)行閱讀，機(jī)器按照規(guī)范也可以進(jìn)行文字識(shí)別，武林秘籍可以寫成文字讓所有人練習(xí)，人的思想也可以寫成文字進(jìn)行傳播。人類的很多經(jīng)典書籍都被翻譯成了多國(guó)文字，Swagger的描述同樣也支持用YAML、XML或JSON來(lái)表示，含義都是一致的。Swagger UI通過(guò)任意一種形式的Swagger描述信息就能渲染出酷炫的API文檔，服務(wù)端接口代碼生成工具也能通過(guò)這個(gè)描述信息生成Controller代碼，圍繞著Swagger，一個(gè)強(qiáng)大的API生態(tài)環(huán)境就出現(xiàn)了。

那么就是說(shuō)，以前我用Markdown寫文檔，現(xiàn)在我用YAML/XML/JSON寫文檔就行了？

是的，但Swagger功能不止如此。使用Swagger可以分為兩種情況：

• 項(xiàng)目未開(kāi)始，需要先定義好API使前端和后端能夠同時(shí)開(kāi)發(fā)；

• API已完成，需要提供文檔；

第二種情況，我們確實(shí)可以直接開(kāi)始編寫一個(gè)JSON或者YAML文件來(lái)描述現(xiàn)有的API（使用Swagger-Editor），不過(guò)這里我們主要介紹第一種情況，全方位感受Swagger。

繼續(xù)之前，我們先介紹一下另一個(gè)東西（也許這么多新概念就是把大家弄暈了的原因……找到Swaager的應(yīng)用最佳實(shí)踐需要一點(diǎn)點(diǎn)時(shí)間，請(qǐng)繼續(xù)看）。

Annotation

Annotation是Java引入的一個(gè)概念，簡(jiǎn)單來(lái)說(shuō)就是用來(lái)給對(duì)應(yīng)的源代碼添加額外的元數(shù)據(jù)（關(guān)于數(shù)據(jù)的更詳細(xì)的數(shù)據(jù)）的一種語(yǔ)法。Annotation本身不影響代碼的執(zhí)行，只能通過(guò)額外的工具解析或執(zhí)行，通常用來(lái)提供代碼檢查、數(shù)據(jù)類型標(biāo)注等功能。由于Annotation的強(qiáng)大，很多編程語(yǔ)言都引入了這個(gè)概念，包括PHP。

那么，如果我們能將Swagger的描述用Annotation的方式直接寫在Controller上，豈不是既方便又好維護(hù)？

結(jié)合Swagger和PHP

在PHP中使用Swagger，我們需要一個(gè)工具去編寫和解析Annotation到Swagger的描述（例如JSON形式），Swagger豐富的生態(tài)不是吹的，這里我們直接使用前人寫好的swagger-php。而編寫API我們則使用Laravel框架(5.1)。當(dāng)然，swagger-php本身和用哪種框架開(kāi)發(fā)是沒(méi)關(guān)系的。

首先在Laravel項(xiàng)目中安裝swagger-php：

$ composer require zircote/swagger-php

接著定義一個(gè)Controller用來(lái)測(cè)試：

$ artisan make:controller SwaggerController --plain

在Controller中加上兩個(gè)方法：

<?php
namespace App\Http\Controllers;
use Illuminate\Http\Request;
use App\Http\Requests;
use App\Http\Controllers\Controller;
class SwaggerController extends Controller
{
    /**
     * 返回JSON格式的Swagger定義
     */
    public function getJSON()
    {
    }
    /**
     * 假設(shè)是項(xiàng)目中的一個(gè)API
     */
    public function getMyData()
    {
    }
}

相應(yīng)的，我們?cè)黾勇酚膳渲茫?/p>

<?php
Route::group(['prefix' => 'swagger'], function () {
    Route::get('json', 'SwaggerController@getJSON');
    Route::get('my-data', 'SwaggerController@getMyData');
});

我們先實(shí)現(xiàn)getJSON方法，使其能夠返回合法的Swagger定義：

<?php
// ...
    /**
     * 返回JSON格式的Swagger定義
     *
     * 這里需要一個(gè)主`Swagger`定義：
     * @SWG\Swagger(
     *   @SWG\Info(
     *     title="我的`Swagger`API文檔",
     *     version="1.0.0"
     *   )
     * )
     */
    public function getJSON()
    {
        // 你可以將API的`Swagger Annotation`寫在實(shí)現(xiàn)API的代碼旁，從而方便維護(hù)，
        // `swagger-php`會(huì)掃描你定義的目錄，自動(dòng)合并所有定義。這里我們直接用`Controller/`
        // 文件夾。
        $swagger = \Swagger\scan(app_path('Http/Controllers/'));
        return response()->json($swagger, 200);
    }
// ...

訪問(wèn)一下/swagger/json，如果我們看到下面的返回就說(shuō)明搭建成功了：

{"swagger":"2.0","info":{"title":"\u6211\u7684`Swagger`API\u6587\u6863","version":"1.0.0"},"paths":{},"definitions":{}}

然后我們來(lái)定義項(xiàng)目中的API接口：

<?php 
// ...
    /**
     * 假設(shè)是項(xiàng)目中的一個(gè)API
     *
     * @SWG\Get(path="/swagger/my-data",
     *   tags={"project"},
     *   summary="拿一些神秘的數(shù)據(jù)",
     *   description="請(qǐng)求該接口需要先登錄。",
     *   operationId="getMyData",
     *   produces={"application/json"},
     *   @SWG\Parameter(
     *     in="query",
     *     name="reason",
     *     type="string",
     *     description="拿數(shù)據(jù)的理由",
     *     required=true,
     *   ),
     *   @SWG\Response(response="default", description="操作成功")
     * )
     */
    public function getMyData()
    {
        //todo 待實(shí)現(xiàn)
    }
// ...

雖然API還沒(méi)有真正實(shí)現(xiàn)，但是我們的第一個(gè)API文檔已經(jīng)完成了(后面我們?cè)谥v每個(gè)Annotation的含義)！來(lái)看看現(xiàn)在JSON接口的輸出內(nèi)容：

{"swagger":"2.0","info":{"title":"\u6211\u7684`Swagger`API\u6587\u6863","version":"1.0.0"},"paths":{"\/swagger\/my-data":{"get":{"tags":["project"],"summary":"\u62ff\u4e00\u4e9b\u795e\u79d8\u7684\u6570\u636e","description":"\u8bf7\u6c42\u8be5\u63a5\u53e3\u9700\u8981\u5148\u767b\u5f55\u3002","operationId":"getMyData","produces":["application\/xml","application\/json"],"parameters":[{"name":"reason","in":"query","description":"\u62ff\u6570\u636e\u7684\u7406\u7531","required":true,"type":"string"}],"responses":{"default":{"description":"\u64cd\u4f5c\u6210\u529f"}}}}},"definitions":{}}

Swagger-UI

當(dāng)然，如果直接把這個(gè)甩給前端同學(xué)，他們一定會(huì)一臉懵逼看著你的……為了把JSON定義轉(zhuǎn)化為可以閱讀和交互的API，我們還需要用到Swagger-UI。Swagger-UI是一套不依賴后端的純HTML程序，只需要將之前輸出JSON的接口地址給它，就能得到一個(gè)強(qiáng)大的API文檔了。為了避免請(qǐng)求跨域問(wèn)題，我們將Swagger-UI部署在項(xiàng)目的public/swagger-ui/文件夾中。安裝非常簡(jiǎn)單，直接在GitHub上下載壓縮包，解壓縮之后將dist/文件夾下的所有內(nèi)容放到public/swagger-ui/就行了。

在訪問(wèn)之前，我們先改一下Swagger-UI默認(rèn)請(qǐng)求的接口地址，打開(kāi)public/swagger-ui/index.html，找到以下代碼：

<script type="text/javascript">
    $(function () {
        var url = window.location.search.match(/url=([^&]+)/);
        if (url && url.length > 1) {
          url = decodeURIComponent(url[1]);
        } else {
          url = "http://petstore.swagger.io/v2/swagger.json"; // 就是這一行
        }
// ...

將url改成我們自己接口的地址，例如http://my.project/swagger/json。打開(kāi)瀏覽器，訪問(wèn)/swagger-ui/，就能看到API文檔了：

高大上的界面

在這個(gè)高大上的API文檔上稍微玩一會(huì)兒，你可能冒出幾個(gè)問(wèn)題：

• 有沒(méi)有中文支持？

• 每次都要點(diǎn)一次才能展開(kāi)API列表好麻煩，能默認(rèn)展開(kāi)嗎？

• 右下角那個(gè)ERROR是什么意思？

可能你還有更多問(wèn)題，但我們先說(shuō)這三個(gè)吧…

設(shè)置中文

Swagger-UI支持多國(guó)語(yǔ)言，還是打開(kāi)swagger-ui/index.html，大約在30行左右：

// ...
    <!-- Some basic translations -->
    <!--<script src='lang/translator.js' type='text/javascript'></script>-->
    <!--<script src='lang/ru.js' type='text/javascript'></script>-->
    <!-- <script src='lang/en.js' type='text/javascript'></script> -->
// ...

我們改為：

// ...
    <!-- Some basic translations -->
    <script src='lang/translator.js' type='text/javascript'></script>
    <script src='lang/zh-cn.js' type='text/javascript'></script>
// ...

這樣就會(huì)變成中文了：

親切的中文界面

API列表默認(rèn)展開(kāi)

大概在swagger-ui/index.html的74行左右有以下代碼：

// ...
    onFailure: function(data) {
      log("Unable to Load SwaggerUI");
    },
    docExpansion: "none", // 這一行就是用來(lái)設(shè)置文檔默認(rèn)展開(kāi)層級(jí)的
    jsonEditor: false,
// ...

這個(gè)配置有三個(gè)值：

• none 折疊所有內(nèi)容

• list 展開(kāi)所有分組的API列表

• full 展開(kāi)所有分組的API列表以及每個(gè)API的請(qǐng)求細(xì)節(jié)

一般來(lái)說(shuō)設(shè)置為list就可以了。

去掉ERROR提示

Swagger-UI默認(rèn)會(huì)將你的接口JSON傳給swagger.io進(jìn)行格式驗(yàn)證，然后對(duì)于我們已經(jīng)使用了swagger-php的項(xiàng)目來(lái)說(shuō)基本不需要（因?yàn)閷戝e(cuò)了Annotation的話會(huì)造成Swagger JSON接口報(bào)錯(cuò)），而且內(nèi)部項(xiàng)目有時(shí)也不方便暴露，所以我們可以關(guān)閉驗(yàn)證功能來(lái)去除右下角的ERROR提示圖標(biāo)。這個(gè)配置并不存在于swagger-ui/index.html中，我們需要手動(dòng)在Swagger UI聲明時(shí)設(shè)置一個(gè)新參數(shù)：

// ...
    window.swaggerUi = new SwaggerUi({
        // ...
        validatorUrl: null, //添加這個(gè)配置
    });
// ...

再次刷新之后驗(yàn)證提示就徹底消失了。

如果你需要這個(gè)驗(yàn)證提示，但又不想使用swagger.io的公用服務(wù)，你也可以自己搭建一個(gè)，點(diǎn)這里查看Swagger Validator Badge的使用方法。

折騰成果

折騰后的成果

自定義Swagger UI

Swagger UI本身提供了很多配置和參數(shù)供用戶自定義，點(diǎn)這里查看，大家可以隨意發(fā)揮。

到此這篇關(guān)于PHP Laravel 使用Swagger生成API文檔(基本概念和環(huán)境搭建)的文章就介紹到這了,更多相關(guān)PHP Laravel 生成API文檔內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評(píng)論