在PHPer中，很多人聽說過Swagger，部分人知道Swagger是用來做API文檔的，然而只有少數(shù)人真正知道怎么正確使用Swagger，因為PHP界和Swagger相關的資料實在是太少了。所以鄙人斗膽一試，希望能以本文幫助到大家了解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是一種簡單、強大的RESTful API表現(xiàn)形式。
其擁有地球上最大的API工具生態(tài)環(huán)境，無數(shù)程序員在幾乎所有主流語言和開發(fā)環(huán)境中添加了對Swagger的支持。
只要你的API添加對Swagger的支持，你就等于擁有了可交互的API文檔，SDK代碼生成以及外部使用友好的API。

• Swagger.io首頁

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

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

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

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

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

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

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

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

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

Annotation

Annotation是Java引入的一個概念，簡單來說就是用來給對應的源代碼添加額外的元數(shù)據(jù)（關于數(shù)據(jù)的更詳細的數(shù)據(jù)）的一種語法。Annotation本身不影響代碼的執(zhí)行，只能通過額外的工具解析或執(zhí)行，通常用來提供代碼檢查、數(shù)據(jù)類型標注等功能。由于Annotation的強大，很多編程語言都引入了這個概念，包括PHP。

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

結(jié)合Swagger和PHP

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

首先在Laravel項目中安裝swagger-php：

$ composer require zircote/swagger-php

接著定義一個Controller用來測試：

$ artisan make:controller SwaggerController --plain

在Controller中加上兩個方法：

<?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()
    {
    }
    /**
     * 假設是項目中的一個API
     */
    public function getMyData()
    {
    }
}

相應的，我們增加路由配置：

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

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

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

訪問一下/swagger/json，如果我們看到下面的返回就說明搭建成功了：

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

然后我們來定義項目中的API接口：

<?php 
// ...
    /**
     * 假設是項目中的一個API
     *
     * @SWG\Get(path="/swagger/my-data",
     *   tags={"project"},
     *   summary="拿一些神秘的數(shù)據(jù)",
     *   description="請求該接口需要先登錄。",
     *   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 待實現(xiàn)
    }
// ...

雖然API還沒有真正實現(xiàn)，但是我們的第一個API文檔已經(jīng)完成了(后面我們在講每個Annotation的含義)！來看看現(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

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

在訪問之前，我們先改一下Swagger-UI默認請求的接口地址，打開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。打開瀏覽器，訪問/swagger-ui/，就能看到API文檔了：

高大上的界面

在這個高大上的API文檔上稍微玩一會兒，你可能冒出幾個問題：

• 有沒有中文支持？

• 每次都要點一次才能展開API列表好麻煩，能默認展開嗎？

• 右下角那個ERROR是什么意思？

可能你還有更多問題，但我們先說這三個吧…

設置中文

Swagger-UI支持多國語言，還是打開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>
// ...

這樣就會變成中文了：

親切的中文界面

API列表默認展開

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

// ...
    onFailure: function(data) {
      log("Unable to Load SwaggerUI");
    },
    docExpansion: "none", // 這一行就是用來設置文檔默認展開層級的
    jsonEditor: false,
// ...

這個配置有三個值：

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

• list 展開所有分組的API列表

• full 展開所有分組的API列表以及每個API的請求細節(jié)

一般來說設置為list就可以了。

去掉ERROR提示

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

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

再次刷新之后驗證提示就徹底消失了。

如果你需要這個驗證提示，但又不想使用swagger.io的公用服務，你也可以自己搭建一個，點這里查看Swagger Validator Badge的使用方法。

折騰成果

折騰后的成果

自定義Swagger UI

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

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

最新評論