再見Swagger UI 國人開源了一款超好用的 A

再見Swagger UI 國人開源了一款超好用的 API 文檔生成框架，真香

景

最近，棧長發現某些國內的開源項目都使用到了 Knife4j 技術，看名字就覺得很鋒利啊！

是不是這樣的縮寫呢：

Knife4j=Knife for Java ？

Java 匕首？

看起來很牛逼的樣子，當然，這是我簡單的猜測，從字面上并不能猜到它是干嘛用的！

那么它究竟是一個什么樣的框架呢？

Knife4j 簡介

Knife4j 的前身是 swagger-bootstrap-ui，其實就是一個純 Swagger UI 的皮膚項目，用過 Swagger 的應該都知道，Swagger UI 是不怎么好用的，并不太適合國人，所以 swagger-bootstrap-ui 項目就誕生了。

swagger-bootstrap-ui 后面為了滿足許多個性化的需求，又加入了許多豐富的服務端特性，不再僅僅只是專注于前端 UI 皮膚了，所以又改名：knife4j。

取名 knife4j 是希望它能像一把匕首一樣小巧、輕量，并且功能強悍，更是希望它能成為 Swagger 接口文檔服務的通用性增強型解決方案。

Knife4j 由國人程序員蕭明于 2017 年開源，到現在已經 4 年多了，看了下 Star 數已經超過 4.7k+ 了：

Knife4j 還獲得了 GVP 項目稱號，即 Gitee 最有價值的開源項目，并且我發現現在越來越多的開源項目都在使用它，Swagger UI 可以扔掉了。。

官網地址：

https://doc.xiaominfo.com/knife4j/

開源地址：

https://gitee.com/xiaoym/knife4j

Knife4j 界面賞鑒

Knife4j 采用了 Vue + And Design Vue 組件進行重寫，相關界面拿出來供大家賞鑒。

接口文檔顯示界面：

接口調試界面：

Swagger Models 功能：

支持導出離線 Markdown、Html：

knife4j 果然非常強大，整個界面基于左右菜單式的布局方式，支持多標簽同時打開展示、切換，文檔和調試也更清晰，感覺更符合國人的操作習慣吧。。

Knife4j 實戰

knife4j 目前主要支持以 Java 開發為主，并且支持 Spring MVC、Spring Boot、Spring Cloud 框架的集成使用。

本文棧長就以 Spring Boot 為基礎實戰下吧：

Spring Boot 2.5.0
Knife4j 2.0.9
Maven 3.6.3
JDK 1.8

注意： 使用 Knife4j 2.0.6+ 版本，Spring Boot 的版本要求 2.2.x+

1、Knife4j 依賴引入

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.9</version>
</dependency>

2、Knife4j 配置

開啟增強功能及基本的登錄認證：

knife4j:
  # 開啟增強
  enable: true
  # 開啟登錄認證
  basic:
    enable: true
    username: test
    password: test

支持個性化配置項，如接口地址、接口描述屬性、UI 增強等個性化配置功能：

/**
 * Knife4j 配置類
 * 來源微信公眾號：Java技術棧
 * 作者：棧長
 */
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

    @Bean(value="defaultDocket")
    public Docket defaultDocket() {
        // 聯系人信息
        Contact contact=new Contact("公眾號：Java技術棧", "https://www.javastack.cn", "xx@javastack.cn");

        // 創建 Docket
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("Knife4j 測試")
                        .description("Knife4j Test")
                        .termsOfServiceUrl("https://www.javastack.cn")
                        .contact(contact)
                        .version("1.0")
                        .build())
                .groupName("1.x")
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.javastack.springboot.knife4j.api"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

}

Spring Boot 基礎就不介紹了，送你一份《Spring Boot 學習筆記》，高清理論＋實戰版，照著學習，沒有不會的，最新版正在努力更新中，可以持續關注公眾號 Java技術棧，會第一時間分享給大家。

3、新增測試接口

新增兩個測試接口，一個登錄（POST），一個問好（GET）。

/**
 * Knife4j 測試接口
 * 來源微信公眾號：Java技術棧
 * 作者：棧長
 */
@Api(tags="測試模塊")
@RestController
public class Knife4jController {

    /**
     * Knife4j 測試接口問好
     * 來源微信公眾號：Java技術棧
     * 作者：棧長
     */
    @ApiImplicitParam(name="name", value="名稱", required=true)
    @ApiOperation(value="公眾號Java技術棧向你問好！")
    @ApiOperationSupport(order=2, author="棧長")
    @GetMapping("/knife4j/hi")
    public ResponseEntity<String> hello(@RequestParam(value="name") String name) {
        return ResponseEntity.ok("Hi:" + name);
    }

    /**
     * Knife4j 測試接口登錄
     * 來源微信公眾號：Java技術棧
     * 作者：棧長
     */
    @ApiImplicitParams({
            @ApiImplicitParam(name="username", value="用戶名", required=true),
            @ApiImplicitParam(name="password", value="密碼", required=true)
    })
    @ApiOperation(value="接口登錄！")
    @ApiOperationSupport(order=1, author="棧長")
    @PostMapping("/knife4j/login")
    public ResponseEntity<String> login(@RequestParam(value="username") String username,
                                        @RequestParam(value="password") String password) {
        if (StringUtils.isNotBlank(username) && "javastack".equals(password)) {
            return ResponseEntity.ok("登錄成功:" + username);
        }
        return ResponseEntity.ok("用戶名或者密碼有誤:" + username);
    }

}

上面為了支持接口順序和接口作者，使用了 Knife4j 的@ApiOperationSupport 注解，其他的均為 Swagger 自帶的注解，從該目錄下看還支持下面的注解：

更多可去官網進行學習。

完整的 Demo 代碼就不一一帖了，本節教程所有實戰源碼已上傳到這個倉庫：

https://github.com/javastacks/spring-boot-best-practice

4、Knife4j 測試

啟動應用，打開 Knife4j 文檔頁：

http://localhost:8080/doc.html

登錄認證

主頁信息

主頁會顯示一些已經配置好的文檔參數及接口統計信息，并且在首頁模塊菜單中也看到了我們的測試模塊的兩個接口。

接口文檔：

登錄接口文檔

問好接口文檔

調試一下：

登錄失敗

登錄成功

問好成功

這里棧長使用了接口排序、還有接口作者功能，另外還支持分組排序、自定義文檔、Swagger 資源保護、導出 Markdown、參數緩存等眾多強大功能，增強功能多達 29 項，有興趣的可以自行嘗試...

總結

好了，今天棧長給大家介紹了國人程序員開源的一款 Knife4j 項目，也就是 Swagger 的增強版，毫無疑問要比 Swagger UI 更強大，更好用，也符合國人的習慣！

如果你也在使用 Swagger，可以考慮使用 Knife4j，它不僅有更強大的 UI，更有多達 29 項的增強功能，它們并不是替代關系，就像 Mybatis Plus 和 Mybatis 的關系一樣，它能助你更進一步提高開發生產力。

如果你也在使用 Knife4j，歡迎留言分享哦！

本節教程所有實戰源碼已上傳到這個倉庫：

https://github.com/javastacks/spring-boot-best-practice

來源：https://mp.weixin.qq.com/s/Cx5yieBLZkvDKM7jODVogQ
作者：Java技術棧

這個移動時代，企業正在迅速擁抱移動解決方案，使他們的業務成為更高的預期。雖然有幾種方法可用于移動應用開發，但HTML5移動應用開發是最受歡迎的。雖然具有很少或根本沒有技術知識的人員可以聘請開發人員獲得多種應用程序來滿足他們的需求，但是有許多有魅力的HTML5框架和工具可以支持敏捷和輕松的移動開發。

在這篇文章中，我將發現已知的用于設計和開發移動應用程序的神話般接口的HTML5框架。這些框架包括包含JavaScript和CSS文件的庫。這些庫允許開發人員精通開發移動應用程序，而不需要實現任何本機代碼。

沒有任何進一步的煩惱，讓我們提供最好的HTML5移動UI框架。

Kendo UI

Kendo UI是最受歡迎的HTML5框架之一，加載了高端功能。您可以通過此框架輕松開發無價的跨平臺移動應用程序。這個快速和輕便的平臺配備了一套超過70個UI小部件; 這個強大的集是完全基于jQuery的。在提供AngularJS集成的同時，它還支持Bootstrap并提供離線數據解決方案。它還提供了13個內置主題的壓倒性的列表，可以定制，以創建所需的外觀和感覺。

對于現場的新手，如果您擁有jQuery（可以輕松學習）的專業知識，那么開始使用Kendo UI就不難。此外，它還包括各種開源工具等

Bootstrap

Bootstrap是另一個支持HTML，CSS和JS的高級框架，它允許人們通過響應式布局來開發美觀的移動應用程序。這個絕對框架的直觀和簡單的界面允許具有初學者，中級或高級技能的人們以期望的方式精通開發移動應用程序。為了幫助您在這個平臺上方便地工作，它包括基于HTML和CSS的設計模板。您可以使用這些模板創建表單，排版，圖像輪播，導航等。

Ionic

Ionic是一個非常棒的HTML5框架，可以幫助開發先進的混合移動應用程序。它基本上是一個開源的前端SDK，它使用CSS，HTML和JavaScript來提供高效的混合移動應用開發。它包含可以幫助您開發高度交互式移動應用程序的工具。此外，它是用CSS擴展構建的--SASS（Syntactically Awesome StyleSheets），并針對AngularJS進行了優化。你可以很容易的開始運行這個框架，這很容易操作; 如果需要，您還可以參考互聯網上提供的便捷教程。

Sencha Touch

Sencha Touch是一個令人敬畏的HTML5和JavaScript框架，可以創建高端跨平臺移動網絡應用程序。這個基于MVC的框架為移動設備和驚人的主題提供了超過50個輝煌的UI組件，擁有原生的視覺吸引力。Sencha Touch開發的應用程序與所有主流移動平臺兼容。其本土化的UI小部件和強大的自適應布局增強了用戶交互，從而增加了其可信度。

Onsen UI

Onsen UI是一個基于元素的自定義框架，可以設計出令人難以置信的應用程序。它旨在提供具有優異UX的確定性HTML5應用程序，而不是提及本機類的性能。它本質上是響應的，因此，允許人們有效地瞄準大量的屏幕尺寸，而不會影響質量。您可以通過這個開源框架的易于使用的界面，精通開發混合應用程序。此外，它還支持Apache Cordova和PhoneGaps。

Intel SDK

Intel SDK是另一個令人驚奇的HTML5框架，在全球范圍內廣受歡迎，用于敏捷移動應用程序開發。您可以輕松開發跨平臺移動應用程序，具有所需的外觀和感覺。它通過審查工作流程使設計，開發，調試和部署相當簡單。

所有這些框架提供最優秀的性能，您可以通過考慮您的項目需求和業務目標來簡化您的選擇。選擇最適合的框架，并開發出具有迷人而卓越UI的移動應用。

halApi開源接口框架

讀音：派框架，官網：https://www.phalapi.net/

PhalApi是一個PHP輕量級開源接口框架，致力于快速開發接口服務。支持HTTP/SOAP/RPC等協議，可用于搭建接口/微服務/RESTful接口/Web Services。承諾永久免費，可用于商業用途。

它支持自動生成接口文檔、自動進行參數校驗、自動生成單元測試代碼、自動擁有CURD數據接口、自動安裝程序，讓接口開發更簡單、更高效、更專業。

PhalApi官網截圖：

在線示例

使用PhalApi開源接口框架，能快速開發編寫你的API接口，并能自動生成在線接口文檔。

在線示例：

在線接口文檔：http://demo.phalapi.net/docs.php
接口詳情文檔（以默認接口為例）：http://demo.phalapi.net/docs.php?service=App.Site.Index&detail=1&type=fold
默認接口服務：http://demo.phalapi.net/?s=App.Site.Index

PhalApi會根據你編寫的接口的參數配置和代碼注釋，自動實時生成在線接口文檔。接口列表頁效果類似如下：

PhalApi還支持在線接口測試、請求示例說明、生成離線版HTML接口文檔、實時更新。接口文檔詳情頁效果類似如下：

快速安裝

composer一鍵安裝

使用composer創建項目的命令，可實現一鍵安裝。

$ composer create-project phalapi/phalapi

溫馨提示：關于composer的使用，請參考Composer 中文網 / Packagist 中國全量鏡像。

手動下載安裝

或者，也可以進行手動安裝。將此Git項目代碼下載解壓后，進行可選的composer更新，即：

$ composer update

部署

Nginx配置

如果使用的是Nginx，可參考以下配置。

server {
    listen 80;
    server_name dev.phalapi.net;
    # 將根目錄設置到public目錄
    root /path/to/phalapi/public;
    charset utf-8;


    location / {
        index index.php;
    }


    location ~ \.php$ {
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        # 根據當前環境，選擇合適的通訊方式
        # fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }
}

配置時需要將網站根目錄設置到public目錄，配置保存后重啟nginx。

溫馨提示：推薦將訪問根路徑指向/path/to/phalapi/public。

數據庫配置

如何使用的是MySQL數據庫，參考修改./config/dbs.php數據庫配置。

return array(
    /**
     * DB數據庫服務器集群 / database cluster
     */
    'servers'=> array(
        'db_master'=> array(                       // 服務器標記 / database identify
            'type'=> 'mysql',                 // 數據庫類型，暫時只支持：mysql, sqlserver / database type
            'host'=> '127.0.0.1',             // 數據庫域名 / database host
            'name'=> 'phalapi',               // 數據庫名字 / database name
            'user'=> 'root',                  // 數據庫用戶名 / database user
            'password'=> '',                      // 數據庫密碼 / database password
            'port'=> 3306,                    // 數據庫端口 / database port
            'charset'=> 'UTF8',                  // 數據庫字符集 / database charset
            'pdo_attr_string'=> false,           // 數據庫查詢結果統一使用字符串，true是，false否
            'driver_options'=> array(              // PDO初始化時的連接選項配置
                // 若需要更多配置，請參考官方文檔：https://www.php.net/manual/zh/pdo.constants.php
            ),
        ),
    ),


    // 更多代碼省略……
);

最后，需要給runtime目錄添加寫入權限。

運行和使用

調用接口

在PhalApi，你可以通過service參數（短名字是s參數）指定需要調用的接口服務。例如，訪問默認接口服務。

http://dev.phalapi.net/?s=App.Site.Index

接口請求后結果輸出類似如下：

{
    "ret": 200,
    "data": {
        "title": "Hello PhalApi",
        "version": "2.4.2",
        "time": 1501079142
    },
    "msg": ""
}

對應執行的PHP代碼在./src/app/Api/Site.php文件，源碼片段如下：

<?php
namespace App\Api;
use PhalApi\Api;


/**
 * 默認接口服務類
 * @author: dogstar <chanzonghuang@gmail.com> 2014-10-04
 */
class Site extends Api {
    public function getRules() {
        return array(
            'index'=> array(
                'username'=> array('name'=> 'username', 'default'=> 'PhalApi', 'desc'=> '用戶名'),
            ),
        );
    }


    /**
     * 默認接口服務
     * @desc 默認接口服務，當未指定接口服務時執行此接口服務
     * @return string title 標題
     * @return string content 內容
     * @return string version 版本，格式：X.X.X
     * @return int time 當前時間戳
     * @exception 400 非法請求，參數傳遞錯誤
     */
    public function index() {
        return array(
            'title'=> 'Hello ' . $this->username,
            'version'=> PHALAPI_VERSION,
            'time'=> $_SERVER['REQUEST_TIME'],
        );
    }
}

運行效果，截圖如下：

自動生成的接口文檔詳情頁局部截圖如下：

翻譯

修改./public/init.php文件，可設置當前語言。

// 翻譯語言包設定-簡體中文
\PhalApi\SL('zh_cn');


// Setting language to English
\PhalApi\SL('en');

一張圖告訴你如何使用PhalApi 2.x

PhalApi開發文檔

專為PHPer準備的優雅而詳細的開發文檔，基本都能在文檔找到你要的答案，請看：PhalApi 2.x 開發文檔，http://docs.phalapi.net/#/v2.0/。

文檔使用markdown編寫，文檔頁面截圖如下：

開發文檔大綱：

PhalApi 2.x 開發文檔


    前言
        前言
        如何升級PhalApi？


    一、快速開發
        1.1下載與安裝
        1.2 運行Hello World
        1.3 如何請求接口服務
        1.4 接口響應與在線調試
        1.5 Api接口層
        1.6 DataApi通用數據接口
        1.7 Domain領域層與ADM模式
        1.8 Model數據層與數據庫操作
        1.9 DataModel數據基類
        1.10 單元測試
        1.11 自動加載和PSR-4
        1.12 接口文檔
        1.13 初始化


    二、數據庫
        2.1 數據庫連接
        2.2 數據庫與NotORM
        2.3 數據庫使用和查詢
        2.4 數據庫分庫分表策略
        2.5 連接多個數據庫
        2.6 打印和保存SQL語句
        2.7 定制你的Model基類


    三、高級專題
        3.1 接口參數
        3.2 配置
        3.3 日志
        3.4 緩存
        3.5 過濾器(接口簽名)
        3.6 COOKIE
        3.7 加密
        3.8 國際化
        3.9 CURL請求
        3.10 工具和雜項
        3.11 DI服務匯總
        3.12 擴展類庫
        3.13 SDK包的使用
        3.14 腳本命令
        3.15 MQ隊列
        3.16 錯誤處理

2020視頻教程

B站首發，第一課~第十一課，配套有每節課的視頻知識點大綱。

http://docs.phalapi.net/#/v2.0/video_1

視頻課程：

    PhalApi 2020視頻教程
        第一課 B站首發，2020視頻教程開講啦！
        第二課 視頻教程 - 下載和安裝
        第三課 視頻教程 - Hello World
        第四課 視頻教程 - 如何請求接口服務
        第五課 視頻教程 - 接口響應與在線調試
        第六課 視頻教程 - Api接口層
        第七課 視頻教程 - Domain領域業務層與ADM模式解說
        第八課 視頻教程 - Model數據層與數據庫連接
        第九課 視頻教程 - 測試驅動開發與PHPUnit
        第十課 視頻教程 - 自動加載和PSR-4
        第十一課 視頻教程 - 接口文檔
        視頻教程 - 十分鐘體驗PhalApi Pro，讓PHP接口開發更有趣！
        視頻教程 - 茶店應用實戰

子項目

如果對PhalApi開源框架的內部實現、源代碼和技術架構感興趣，可以查看以下子項目。

phalapi/kernal框架內核
phalapi/notorm數據庫包

PhalApi 2.x 版本的系統架構如下：

PhalApi composer 擴展

phalapi/authAuth權限擴展
phalapi/cliCLI擴展類庫
phalapi/fast-routeFastRoute快速路由
phalapi-aliyun-ossPhalApi-OSS阿里云OSS包
phalapi/PHPMailer基于PHPMailer的郵件發送
phalapi/qiniu七牛云存儲接口調用
phalapi/qrcodePhalApi 二維碼擴展
phalapi/pinyinPhalApi 2.x 拼音擴展
phalapi/jwt基于PhalApi2的JWT拓展
chenall/phalapi-weixin微信擴展
phalapi/wechatmini微信小程序擴展
phalapi/ding-com-bot釘釘企業內部webhook機器人擴展
phalapi-pay支持微信支付和支付寶支付

溫馨提示：以上擴展需要先通過composer安裝再使用。更多擴展類庫的使用和開發，請參考文檔：PhalApi框架擴展類庫：http://docs.phalapi.net/#/v2.0/library。

PhalApi應用插件

運營平臺插件
應用用戶插件
加密解密插件
支付寶插件
茶店微信小程序應用
在線接口文檔主題包

溫馨提示：應用插件和composer擴展的區別在于，應用插件顆粒度更大，功能更具體，可能不僅有數據庫、接口、界面、還可能配合其他終端，并且不受composer的規范約束，是PhalApi自主發明和設計的開發方式。更多請參考：第三方應用插件開發教程：http://docs.phalapi.net/#/v2.0/how-to-dev-plugin。

基于PhalApi開發的技術產品

以下產品均使用了PhalApi開源框架，并為官方自主研發的產品，歡迎個人/團隊/企業使用。

接口大師-即刻搭建您的接口開放平臺(原名：PhalApi專業版)

產品官網：http://pro.phalapi.net/

果創云-后端低代碼開發平臺

產品官網：http://yesapi.cn/

YesDev協作云-在線協作你的全部項目

產品官網：https://www.yesdev.cn/

PhalApi 2.x 版本完美詮釋

2.x 版本系統架構

主要分為三層：

phalapi/phalapi 項目應用層，可使用phalapi/phalapi搭建微服務、接口系統、RESTful、WebServices等。
擴展類庫 擴展類庫是指可選的、可重用的組件或類庫，可以直接集成使用，由廣大開發人員維護分享，對應原來的PhalApi-Library項目。
核心框架 分別兩大部分，PhalApi核心部分kernal，以及優化后的notorm。

其中，各自的composer和github項目分別是：

項目	composer	github
phalapi/phalapi	phalapi/phalapi	phalapi/phalapi
擴展類庫	由廣大開發人員共同維護、分享，composer建議統一注冊到phalapi。	由廣大開發人員共同維護、分享，源代碼可維護在開發者各自的Github倉庫。
核心框架	phalapi/kernal	phalapi/kernal

框架核心部分UML靜態結構圖

PhalApi 2.x 版本的核心框架部分的UML靜態結構圖，高清版如下所示：

首先，綠色部分的PhalApi\PhalApi類是整個接口系統的訪問入口，也就是項目應用系統、客戶端使用的關鍵所在。相關的調用代碼，可以參考統一入口文件的實現代碼片段。

$pai=new \PhalApi\PhalApi();
$pai->response()->output();

只需要兩行代碼，便可完成對接口服務的請求響應。

其次，是黃色部分的Api、Domain和Model這三層，也就是我們常說的ADM分層架構。這部分，需要開發人員關注，因為這也是具體項目開發需要自己實現的部分。

最后，是紅色部分的DI依賴注入，也是整個框架的核心所在。不僅在核心框架中使用頻率最高，乃至在項目應用中也會經常被用到。

核心執行流程時序圖

PhalApi 2.x 版本的核心執行流程時序圖，與1.x 版本基本一致，可以看出，不管技術如何升級，PhalApi的最初的核心時序流程仍保持著活力。唯一變化的是各個類名。

代碼倉庫

Gitee碼云 - PhalApi開源接口框架（1.7k Star）

代碼鏈接：https://gitee.com/dogstar/PhalApi

Github - PhalApi開源接口框架（1.4 Star）

代碼鏈接：https://github.com/phalapi/phalapi

版本更新

2021年7月發布更新了 PhalApi 2.17.2 版本。

PhalApi 2.17.2 版本

[BUG修復]

1、SQL記錄，只提取部分必要的參數，避免全部記錄，以及避免記錄密碼等敏感信息到日志文件

2、翻譯和DataApi參數說明補充

3、DataModel調用不存在方法時的異常提示信息，去掉多余的美元符號

4、在線接口文檔模板判斷調整，避免出現warning

更多歷史版本更新日記，請查看：

http://docs.phalapi.net/#/v2.0/changelog

在線咨詢

上一篇：挑戰答題助手app
下一篇：怎么在qt中加載css文件

您的項目需求

*請認真填寫需求信息，我們會在24小時內與您取得聯系。

整合營銷服務商