再见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小时内与您取得联系。

整合营销服务商