Java基础——接口

接口概念

    官方解释：Java接口是一系列方法的声明，是一些方法特征的集合，一个接口只有方法的特征没有方法的实现，因此这些方法可以在不同的地方被不同的类实现，而这些实现可以具有不同的行为（功能）。

    我的解释：接口可以理解为一种特殊的类，里面全部是由全局常量和公共的抽象方法所组成。接口是解决Java无法使用多继承的一种手段，但是接口在实际中更多的作用是制定标准的。或者我们可以直接把接口理解为100%的抽象类，既接口中的方法必须全部是抽象方法。（JDK1.8之前可以这样理解）

接口的特点

    就像一个类一样，一个接口也能够拥有方法和属性，但是在接口中声明的方法默认是抽象的。（即只有方法标识符，而没有方法体）。

• 接口指明了一个类必须要做什么和不能做什么，相当于类的蓝图。
• 一个接口就是描述一种能力，比如“运动员”也可以作为一个接口，并且任何实现“运动员”接口的类都必须有能力实现奔跑这个动作（或者implement move()方法），所以接口的作用就是告诉类，你要实现我这种接口代表的功能，你就必须实现某些方法，我才能承认你确实拥有该接口代表的某种能力。
• 如果一个类实现了一个接口中要求的所有的方法，然而没有提供方法体而仅仅只有方法标识，那么这个类一定是一个抽象类。（必须记住：抽象方法只能存在于抽象类或者接口中，但抽象类中却能存在非抽象方法，即有方法体的方法。接口是百分之百的抽象类）
• 一个JAVA库中接口的例子是：Comparator 接口，这个接口代表了“能够进行比较”这种能力，任何类只要实现了这个Comparator接口的话，这个类也具备了“比较”这种能力，那么就可以用来进行排序操作了。

为什么要用接口

1.     接口被用来描述一种抽象。
2. 因为Java不像C++一样支持多继承，所以Java可以通过实现接口来弥补这个局限。
3. 接口也被用来实现解耦。
4. 接口被用来实现抽象，而抽象类也被用来实现抽象，为什么一定要用接口呢？接口和抽象类之间又有什么区别呢？原因是抽象类内部可能包含非final的变量，但是在接口中存在的变量一定是final，public,static的。

接口的语法实现

    为了声明一个接口，我们使用interface这个关键字，在接口中的所有方法都必须只声明方法标识，而不要去声明具体的方法体，因为具体的方法体的实现是由继承该接口的类来去实现的，因此，接口并不用管具体的实现。接口中的属性默认为Public Static Final.一个类实现这个接口必须实现这个接口中定义的所有的抽象方法。

    一个简单的接口就像这样：拥有全局变量和抽象方法。

    为了实现这个接口，我们使用implements关键词去实现接口：

其中testClass类实现了我们上面刚才定义的 in1 这个接口，既然你要实现接口，也就是实现接口代表的一种能力，那么你就必须去实现接口给你规定的方法，只有把接口给你规定的抽象方法都给实现了，才承认你这个类实现了这个接口，实现了这个接口代表的某种功能。上图实现了接口中规定的display（）方法。

    写一个测试类，用来测试一下我们刚才实现的这个接口，因为testclass类的对象t实现了接口规定的display方法，那么自然而然就可以调用display（）方法咯。

    有兴趣的同学可以去这个在线IDE亲自试一试：点击打开链接

接口的进一步理解

    我们知道，如果某个设备需要向电脑中读取或者写入某些东西，这些设备一般都是采用USB方式与电脑连接的，我们发现，只要带有USB功能的设备就可以插入电脑中使用了，那么我们可以认为USB就是一种功能，这种功能能够做出很多的事情（实现很多的方法），其实USB就可以看做是一种标准，一种接口，只要实现了USB标准的设备我就认为你已经拥有了USB这种功能。（因为你实现了我USB标准中规定的方法），下面是具体的例子：

先声明USB接口：其中规定了要实现USB接口就必须实现接口规定实现的read( )和write( )这两个方法。

interface USB {
    void read();

    void write();
}

然后在写一个U盘类和一个键盘类，这两个类都去实现USB接口。（实现其中的方法）

class YouPan implements USB {

    @Override

    public void read() {

        System.out.println("U盘正在通过USB功能读取数据");

    }

    @Override

    public void write() {

        System.out.println("U盘正在通过USB功能写入数据");

    }

}

这是U盘的具体实现。

class JianPan implements USB {

    @Override

    public void read() {

        System.out.println("键盘正在通过USB功能读取数据");

    }

    @Override

    public void write() {

        System.out.println("键盘正在通过USB功能写入数据");

    }

}

这是键盘的具体实现。

    那么，现在U盘和键盘都实现了USB功能，也就是说U盘和键盘都能够调用USB接口中规定的方法，并且他们实现的方式都不一样。

我们在写一个测试，来看看具体的实现：

public class Main {

    public static void main(String[] args) {

        //生成一个实现可USB接口（标准）的U盘对象

        YouPan youPan = new YouPan();

        //调用U盘的read( )方法读取数据

        youPan.read();

        //调用U盘的write( )方法写入数据

        youPan.write();

        //生成一个实现可USB接口（标准）的键盘对象

        JianPan jianPan = new JianPan();

        //调用键盘的read( )方法读取数据

        jianPan.read();

        //调用键盘的write( )方法写入数据

        jianPan.write();

    }

}

 

结果如下：

    感兴趣的同学可以去在线IDE平台自己验证一下：点击打开链接

关于接口的几个重点

1. 我们不能直接去实例化一个接口，因为接口中的方法都是抽象的，是没有方法体的，这样怎么可能产生具体的实例呢？但是，我们可以使用接口类型的引用指向一个实现了该接口的对象，并且可以调用这个接口中的方法。因此，上图中最后的方法调用我们还可以这样写：（实际上就是使用了Java中多态的特性）

public class Main {

    public static void main(String[] args) {

        //生成一个实现可USB接口（标准）的U盘对象

        //但是使用一个接口引用指向对象

        //USB接口类引用可以指向一个实现了USB接口的对象

        USB youPan = new YouPan();

        //调用U盘的read( )方法读取数据

        youPan.read();

        //调用U盘的write( )方法写入数据

        youPan.write();

        //生成一个实现可USB接口（标准）的键盘对象

        //但是使用一个接口引用指向对象

        //USB接口类引用可以指向一个实现了USB接口的对象

        USB jianPan = new JianPan();

        //调用键盘的read( )方法读取数据

        jianPan.read();

        //调用键盘的write( )方法写入数据

        jianPan.write();

    }

}                                                                                                                                     

 2.一个类可以实现不止一个接口。

3.一个接口可以继承于另一个接口，或者另一些接口，接口也可以继承，并且可以多继承。

4.一个类如果要实现某个接口的话，那么它必须要实现这个接口中的所有方法。

5.接口中所有的方法都是抽象的和public的，所有的属性都是public,static,final的。

6.接口用来弥补类无法实现多继承的局限。

7.接口也可以用来实现解耦。

接口的通俗理解

    前面我们讲多态的时候用“空调”——“遥控器”的方式去理解多态，实际上在上面的的几个重点中的第一条讲的也是多态的实现，比如，我们可以把“节能”作为一种标准，或者说节能就是一个“接口”，这个接口中有一个方法，叫做变频方法，任何空调，如果要称得上叫做节能空调的话，那么必须实现“节能”这个接口，实现“节能”这个接口，也就必须实现“节能”接口中规定实现的“变频”方法，这样才算是真正的实现了“节能”这个接口，实现了“节能”这个功能。

    当某个空调实现了“节能”接口后，这个空调就具备了节能的功能，那么我们也可以不用空调类的引用指向空调对象，我们可以直接使用一个“节能”接口类型引用的“遥控器”去指向“空调”，虽然这个“遥控器”上面只有一个按键，只有一个“变频”的方法，但是“遥控器”所指向的空调是实现了“节能”这个接口的，是有“变频”方法的实现的，我们用这个只有一个“变频”方法的遥控器去命令空调调用“变频”方法，也是行得通的，实在不清楚的同学可以去看我的另一篇文章：JAVA之对象的多态性。

接口的标识用法

    虽然接口内部定义了一些抽象方法，但是并不是所有的接口内部都必须要有方法，比如Seriallizable接口，Seriallizable接口的作用是使对象能够“序列化”，但是Seriallizable接口中却没有任何内容，也就是说，如果有一个类需要实现“序列化”的功能，则这个类必须去实现Seriallizable接口，但是却并不用实现方法（因为接口中没有方法），此时，这个Serilizable接口就仅仅是一个“标识”接口，是用来标志一个类的，标志这个类具有这个“序列化”功能。具体的实现请参考我的另一篇文章——JAVA之IO流。

接口在生活中的思想体现

其实，在我们的生活当中，有很多地方都体现了“接口”的思想，想必，正在阅读这篇博文的你，是不是也喜欢摄影呢？

玩摄影的童鞋都知道，单反由相机和镜头组成，相机分不同的型号，有半画幅的，也有全画幅的。镜头也是一样的，分长焦，短焦；还有定焦和变焦。每种镜头都有各自特定的发挥场景。正是因为镜头的多元化，使得我们的摄影能够“术业有专攻”。大家想一想，如果我们的单反相机部分和镜头部分是固定在一起的，不能够更换镜头，那么将会多么的糟糕啊！

因此，每个相机品牌为了能够兼容不同的镜头，各自发布了一套镜头卡口的标准，这套标准就好比我们前面提到的“接口”，都是某种“约束”。举个栗子，我们佳能的相机，不管你是哪一家镜头生产厂商，腾龙也好，适马也好，只要你按照我佳能卡口的标准来生产镜头，你生产的镜头都能够很好的在我佳能相机上面驱动。

因此，当我们打开“狗东”，准备给自己的新相机买镜头的时候，就不难发现，我们需要根据自己相机的品牌来挑选特定卡口的镜头，这样的镜头才能被我们的相机正常驱动。

回到Java上面来说，其实接口给我们带来的最大的好处就是“解耦”了，相机能够搭配不同的镜头，才能有各种各样的搭配玩法，变得更加的灵活。在软件系统中也是一样的，接口可以有很多不同“特色”的实现类，我们只需要声明同一个接口，却可以引用很多个该“接口”引申出来的“子类”，这不也大大增强了我们软件系统中组件的灵活性吗？

聪明的你，对于“接口”的理解是不是又更加的深入了呢？

基础不牢？新手不友好？无人带路？关注《扬俊的小屋》公众号吧！

参考资料

1.《Java开发实战经典》 李兴华著  清华大学出版社

2.https://www.geeksforgeeks.org/interfaces-in-java  作者：Mehak Kumar. and Nitsdheerendra.   翻译：刘扬俊

博客文章版权说明

第一条 本博客文章仅代表作者本人的观点，不保证文章等内容的有效性。

第二条 本博客部分内容转载于合作站点或摘录于部分书籍，但都会注明作/译者和原出处。如有不妥之处，敬请指出。

第三条 在征得本博客作者同意的情况下，本博客的作品允许非盈利性引用，并请注明出处：“作者：____转载自____”字样，以尊重作者的劳动成果。版权归原作/译者所有。未经允许，严禁转载。

第四条 对非法转载者，“扬俊的小屋”和作/译者保留采用法律手段追究的权利。

第五条 本博客之声明以及其修改权、更新权及最终解释权均属“扬俊的小屋”。

第六条 以上声明的解释权归“扬俊的小屋”所有。

目录

1、接口文档

2、接口文档管理工具

-Postman、Swagger、RAP、DOClever对比介绍

3、Swagger

总结

1、接口文档

1.定义：在项目开发汇总，web项目的前后端是分离开发的。应用程序的开发，需要由前后端工程师共同定义接口，编写接口文档，之后大家都根据这个接口文档进行开发，到项目结束前都要一直维护。
2.功能与目的：项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发，项目维护或者项目人员更迭的时候，方便后期人员查看、维护。
3.接口文档规范：

首先了解一下接口：

一份规范的接口文档除了上面提到的请求方法、url、请求参数、返回参数以外，还应该添加接口示例、接口文档版本号、版本修改内容、版本修改时间、修改人，错误代码等。

5.示例：接口文档示例（来源：网络）

2、接口文档管理工具

-Postman、Swagger、RAP、DOClever对比介绍

在项目开发测试中，接口文档是贯穿始终的。前后端开发需要在开发前期进行接口定义并形成文档，QA在功能测试和接口测试的环节也需要依赖于这些接口文档进行测试。接口文档往往以最简单的静态文档的形态存在。然而在紧张的敏捷开发模式下，随着版本迭代，很多接口发生了变化或者被废弃，而开发几乎不会在后期去更新这种静态文档。QA人员阅读“过期”的接口文档是一件痛苦的事情，与开发的沟通成本不降反升。而这些不便于及时维护的静态文档，随着时间的推移最终无人问津。因此，我们想要找到一种长期可维护且轻量便捷的接口文档工具。
Postman是被大家所熟知的网页调试Chrome插件，我们常常用它来进行临时的http请求调试。幸运的是，Postman可以将调试过的请求保存到Collection中。形成的Collection就可以作为一份简单有效且支持在线测试的接口文档，使用同一账号登录就可以做到分享和同步。对QA来说，使用Postman进行接口测试和接口文档维护是同一件事情，测试即文档，维护成本也很低。

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。简单来说，Swagger是一个功能强大的接口管理工具，并且提供了多种编程语言的前后端分离解决方案。Swagger主要包含了以下4个部分：

1. Swagger可以直接嵌入项目中，通过开发时编写注释，自动生成接口文档；

2. Swagger包含了SwaggerEditor，它是使用yaml语言的Swagger API的编辑器，支持导出yaml和json格式的接口文件；

3. Swagger包含了SwaggerUI，它将Swagger Editor编辑好的接口文档以html的形式展示出来；

4. Swagger支持根据定义的接口导出各种语言的服务端或客户端代码。

其中1和4是更加面向开发的内容，开发团队要有自动生成文档的需求，在开发和自测中遵循前后端分离。而2和3是相对可以独立出来的、可供QA人员参考的接口文档管理方案，也是我们主要关注的部分。

Swagger提供了SwaggerEditor和Swagger UI的在线demo，如下图。可以看出，Swagger可以完整地定义一个接口的内容，包括各个参数、返回值的具体结构、类型，SwaggerEditor可以实时进行编辑并在线调试。编辑好的API可以导出为json文件，使用Swagger UI打开即可以看到更美观的接口文档。

Swagger Editor和SwaggerUI的本地部署十分简单，这两者都可以直接从Github上下载源码，将其部署到本地Tomcat服务器上，然后通过浏览器访问即可。官方还提供了其他几种部署方式，具体步骤在帮助文档中有详细说明，这里不再赘述。

RAP是阿里的一套完整的可视化接口管理工具，可以定义接口结构，动态生成模拟数据，校验真实接口正确性。不仅如此，RAP围绕接口定义，提供了一系列包括团队管理、项目管理、文档版本管理、mock插件等服务。

有关RAP的使用，RAP官网提供了非常详细的wiki和视频教程。与Swagger需要使用标记语言编写不同，RAP可以完全可视化地定义项目相关信息，定义接口的请求响应等等，学习成本较低。RAP还为后端开发人员提供了校验接口的功能，为前端开发人员提供了mock数据的工具等。

DOClever是一个可视化接口管理工具,可以分析接口结构，校验接口正确性， 围绕接口定义文档，通过一系列自动化工具提升我们的协作效率。DOClever前后端全部采用了javascript来作为开发语言，前端用的是vue+element UI，后端是express+mongodb，这样的框架集成了高并发，迭代快的特点，保证系统的稳定可靠。

功能如下：

1.可以对接口信息进行编辑管理，支持get,post,put,delete,patch 五种方法，支持 https 和 https 协议，并且支持 query，body，json，raw，rest，formdata 的参数可视化编辑。同时对 json 可以进行无限层次可视化编辑。并且，状态码，代码注入，markdown 文档等附加功能应有尽有。

 2.接口调试运行，可以对参数进行加密，从md5 到 aes 一应俱全，返回参数与模型实时分析对比，给出不一致的地方，找出接口可能出现的问题。如果你不想手写文档，那么试试接口的数据生成功能，可以对接口运行的数据一键生成文档信息。

 3.mock 的无缝整合，DOClever 自己就是一个 mock 服务器，当你把接口的开发状态设置成已完成，本地 mock 便会自动请求真实接口数据，否则返回事先定义好的 mock 数据。

4.支持 postman，rap，swagger 的导入，方便你做无缝迁移，同时也支持 html 文件的导出，方便你离线浏览！

5.项目版本和接口快照功能并行，你可以为一个项目定义 1.0，1.1，1.2 版本，并且可以自由的在不同版本间切换回滚，再也不怕接口信息的遗失，同时接口也有快照功能，当你接口开发到一半或者接口需求变更的时候，可以随时查看之前编辑的接口信息。

6.自动化测试功能，目前市面上类似平台的接口自动化测试大部分都是伪自动化，对于一个复杂的场景，比如获取验证码，登陆，获取订单列表，获取某个特定订单详情这样一个上下文关联的一系列操作无能为力。而 DOClever 独创的自动化测试功能，只需要你编写极少量的 javascript 代码便可以在网页里完成这样一系列操作，同时，DOClever 还提供了后台定时批量执行测试用例并把结果发送到团队成员邮箱的功能，你可以及时获取接口的运行状态。

7.团队协作功能，很多类似的平台这样的功能是收费的，但是 DOClever 觉得好东西需要共享出来，你可以新建一个团队，并且把团队内的成员都拉进来，给他们分组，给他们分配相关的项目以及权限，发布团队公告等等。

DOClever 开源免费，支持内网部署，很多公司考虑到数据的安全性，不愿意把接口放到公网上，没有关系，DOClever 给出一个方便快捷的解决方案，你可以把平台放到自己的内网上，完全不需要连接外网，同时功能一样也不少，即便是对于产品的升级，DOClever 也提供了很便捷的升级方案！

官网： http://doclever.cn

Github: https://github.com/sx1989827/DOClever

码云: https://git.oschina.net/sx1989827/SBDoc

文档: http://doclever.cn/help/help.html

总结

Postman是一个测试向的API小工具，可以非常轻量地维护一份“测试记录”，适合小的测试团队自己使用并维护。Swagger丰富且独立的各个功能使得它可以被应用在各种需求下，不论是开发还是测试都可以使用这个工具，来优化自己的开发过程，进行接口文档维护、接口测试等；但Swagger的学习和接入成本相对较高，需要开发与测试的深入配合。RAP的应用范围非常明确，是一个面向开发人员自测和联调的工具性平台，它更适合以开发为核心对接口进行维护，但目前基本不在维护。DOClever是一款功能比较强大的平台，在国内好评率很高，而且产品完全免费开源，可线下部署；同时产品更新迭代比较频繁，可以看出他们也是在用心做这个产品；

3、Swagger

（swagger使用和教程_青春季风暴-CSDN博客_swagger使用）

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。发现了痛点就要去找解决方案。解决方案用的人多了，就成了标准的规范，这就是Swagger的由来。通过这套规范，你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。这样，如果按照新的开发模式，在开发新版本或者迭代版本的时候，只需要更新Swagger描述文件，就可以自动生成接口文档和客户端服务端代码，做到调用端代码、服务端代码以及接口文档的一致性。

但即便如此，对于许多开发来说，编写这个yml或json格式的描述文件，本身也是有一定负担的工作，特别是在后面持续迭代开发的时候，往往会忽略更新这个描述文件，直接更改代码。久而久之，这个描述文件也和实际项目渐行渐远，基于该描述文件生成的接口文档也失去了参考意义。所以作为Java届服务端的大一统框架Spring，迅速将Swagger规范纳入自身的标准，建立了Spring-swagger项目，后面改成了现在的Springfox。通过在项目中引入Springfox，可以扫描相关的代码，生成该描述文件，进而生成与代码一致的接口文档和客户端代码。这种通过代码生成接口文档的形式，在后面需求持续迭代的项目中，显得尤为重要和高效。

1.说明

现在SWAGGER官网主要提供了几种开源工具，提供相应的功能。可以通过配置甚至是修改源码以达到你想要的效果。

wagger Codegen: 通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包，docker，node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。

Swagger UI:提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。

Swagger Editor: 类似于markendown编辑器的编辑Swagger描述文件的编辑器，该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。

Swagger Inspector: 感觉和postman差不多，是一个可以对接口进行测试的在线版的postman。比在Swagger UI里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。

Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

PS：

Springfox Swagger: Spring 基于swagger规范，可以将基于SpringMVC和Spring Boot项目的项目代码，自动生成JSON格式的描述文件。本身不是属于Swagger官网提供的，在这里列出来做个说明，方便后面作一个使用的展开。

2.基于Spring框架的Swagger流程应用

这里不会介绍Swagger的工具具体如何使用，不会讲yml或者json格式描述文件的语法规范，也不会讲如何在SpringMVC或者Spring Boot中配置Springfox－swagger。这些都能从网上找到，而且配置起来都非常的简单。

这里想讲的是如何结合现有的工具和功能，设计一个流程，去保证一个项目从开始开发到后面持续迭代的时候，以最小代价去维护代码、接口文档以及Swagger描述文件。

2.1 项目开始阶段

一般来说，接口文档都是由服务端来编写的。在项目开发阶段的时候，服务端开发可以视情况来决定是直接编写服务端调用层代码，还是写Swagger描述文件。建议是如果项目启动阶段，就已经搭好了后台框架，那可以直接编写服务端被调用层的代码（即controller及其入参出参对象），然后通过Springfox－swagger 生成swagger json描述文件。如果项目启动阶段并没有相关后台框架，而前端对接口文档追得紧，那就建议先编写swagger描述文件，通过该描述文件生成接口文档。后续后台框架搭好了，也可以生成相关的服务端代码。

2.1 项目迭代阶段

到这个阶段，事情就简单很多了。后续后台人员，无需关注Swagger描述文件和接口文档，有需求变更导致接口变化，直接写代码就好了。把调用层的代码做个修改，然后生成新的描述文件和接口文档后，给到前端即可。真正做到了一劳永逸。

2.3流程

总结一下就是通过下面这两种流程中的一种，可以做到代码和接口文档的一致性，服务端开发再也不用花费精力去维护接口文档。

流程一

流程二

给Mock系统的正常请求及响应全流程数据

很多时候，如果你能在提供接口文档的同时，把所有接口的模拟请求响应数据也提供给前端。或者有Mock系统，直接将这些模拟数据录入到Mock系统中，那将会提高前端的开发效率，减少许多发生在联调时候才会发生的问题。

通过适当地在代码中加入swagger的注解，可以让你的接口文档描述信息更加详细，如果你把每个出入参数的示例值都配上，那前端就可以直接在接口文档中拿到模拟数据。相关的注解类及参数配置可以参考文末他人写的技术文章，这里也不作展开了。

相关示例注解代码和效果图如下：#####Controller代码

@Override
    @ApiOperation(value = "post请求调用示例", notes = "invokePost说明", httpMethod = "POST")
    public FFResponseModel<DemoOutputDto> invokePost(@ApiParam(name="传入对象",value="传入json格式",required=true) @RequestBody @Valid DemoDto input) {
        log.info("/testPost is called. input=" + input.toString());
        return new FFResponseModel(Errcode.SUCCESS_CODE, Errcode.SUCCESS_MSG);
    }

 #####接口请求入参对象  

@Data
@ApiModel(value="演示类",description="请求参数类" )
public class DemoDto implements Serializable {

    private static final long serialVersionUID = 1L;

    @NotNull
    @ApiModelProperty(value = "defaultStr",example="mockStrValue")
    private String strDemo;

    @NotNull
    @ApiModelProperty(example="1234343523",required = true)
    private Long longNum;

    @NotNull
    @ApiModelProperty(example="111111.111")
    private Double doubleNum;

    @NotNull
    @ApiModelProperty(example="2018-12-04T13:46:56.711Z")
    private Date date;
    
}

 #####接口请求出参公共类

@ApiModel(value="基础返回类",description="基础返回类")
public class FFResponseModel<T> implements Serializable {

    private static final long serialVersionUID = -2215304260629038881L;
    // 状态码
    @ApiModelProperty(example="成功")
    private String code;
    // 业务提示语
    @ApiModelProperty(example="000000")
    private String msg;
    // 数据对象
    private T data;

...
}

 #####接口请求出参实际数据对象

@Data
public class DemoOutputDto {

    private String res;

    @NotNull
    @ApiModelProperty(value = "defaultOutputStr",example="mockOutputStrValue")
    private String outputStrDemo;

    @NotNull
    @ApiModelProperty(example="6666666",required = true)
    private Long outputLongNum;

    @NotNull
    @ApiModelProperty(example="88888.888")
    private Double outputDoubleNum;

    @NotNull
    @ApiModelProperty(example="2018-12-12T11:11:11.111Z")
    private Date outputDate;
    
}

效果图

模拟请求数据报文：

模拟返回数据报文：

总结

归根到底，使用Swagger，就是把相关的信息存储在它定义的描述文件里面（yml或json格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。而Springfox-swagger,则可以通过扫描代码去生成这个描述文件，连描述文件都不需要再去维护了。所有的信息，都在代码里面了。代码即接口文档，接口文档即代码。

目前显示部分常用接口部分整理与总结

1.HDMI：是一种全数字化视频和声音发送接口，可以发送未压缩的音频及视频信号（高清多媒体接口（High Definition Multimedia Interface，HDMI）），用我们自己的话来说：HDMI接口就是一种用来传输影像和声音信号的接口，内容制造设备通过HDMI就可以将影像和声音以极高的效率传输到观影设备上。这类接口在智能电视、机顶盒、投影仪等设备中比较常见，其接口呈倒梯形，较偏平；如下图：（HDMI2.0）

HDMI 1.0

最早的HDMI 1.0版本于2002年12月推出，它的最大特点就是整合了音频流的数字接口，与当时PC界面中很流行的DVI接口相比，它更先进，更方便。HDMI 1.0版本支持从DVD到蓝光格式的视频流，而且具备CEC（consumer electronics control）功能，也就是在应用中，可以在所有连接设备间形成一种共通的联络，对设备组具备更方便的控制。

HDMI 1.1

　　2004年5月，HDMI 1.1版本面试。新增对DVD音频的支持。

HDMI 1.2

HDMI1.2版本于2005年8月推出，很大程度上解决了HDMI 1.1支持的分辨率较低、同电脑设备兼容性较差等问题。1.2版像素时钟运行频率达到165MHz，数据量达到4.95 Gbps，因此可以实现1080P。可以认为1.2版解决的是电视的1080P和电脑的点对点问题。

HDMI 1.3

2006年6月HDMI 1.3更新，带来最大的变化是将单链接带宽频率提升到340MHz，也就能让这些液晶电视获得10.2Gbps的数据传输量，1.3版的线是有4对传输通道组成，其中1对通道是时钟通道，另外3对是TMDS通道（最小化传输差分信号），他们的传输速度分别为3.4GBPS。那么3对就是3*3.4=10.2GPBS更是能将HDMI1.1、1.2版本所支持的24位色深大幅扩充至30位、36位及48位（RGB或YCbCr）。HDMI 1.3支持1080P；一些要求不高的3D也支持（理论上不支持，实际有些可以）。

HDMI 1.4

HDMI 1.4版本已经可以支持4K了，但是受制于带宽10.2Gbps，最高只能达到3840×2160分辨率和30FPS帧率。

HDMI 2.0

HDMI 2.0的带宽扩充到了18Gbps，支持即插即用和热插拔，支持3840×2160分辨率和50FPS、60FPS帧率。同时在音频方面支持最多32个声道，以及最高1536kHz采样率。HDMI 2.0并没有定义新的数据线和接头、接口，因此能保持对HDMI 1.x的完美向下兼容，现有的二类数据线可直接使用。HDMI 2.0并不会取代HDMI 1.x，而是基于后者的增强，任何设备要想支持HDMI 2.0必须首先保证对HDMI 1.x的基础性支持

2. VGA接口的定义

VGA（Video Graphics Array），是模拟信号，只能传输视频信号。接口共有15针，分成3排，每排5个孔，是显卡上应用最为广泛的接口类型，绝大多数显卡都带有此种接口。它传输红、绿、蓝模拟信号以及同步信号（水平和垂直信号）。

VGA接口的针脚定义

15个针脚的名称和描述如下：

VGA成像的基本原理

芯片组将显存内数字格式存储的图像（侦）信号经过DAC转换为R，G，B模拟信号，和行、场同步信号，再输出到显示设备成像。

显示器通过光栅扫描的方式。电子束在显示屏幕上有规律的由做左到右，由上到下进行扫描。在扫描过程中，受行同步信号的控制，逐点往右扫，完成一行扫描的时间的倒数称为行频。同时会在行同步周期的脉冲内回到屏幕的左端，受场同步信号的控制，从上往下扫描完成一侦信号，完成此一侦信号周期的倒数称为场频。最后通过不同的像素的组合来形成显示图像。

VGA的优势

虽然VGA是1987年便提出了，发展了很多年，它依然在各行各业发挥着作用，也有着很多自身独有的优势。

（1）VGA 具有分辨率高、显示速率快、颜色丰富等优点。

（2）VGA 显示系统还具有成本低、结构简单、应用灵活的优点。

（3）VGA 显示输出 RGB 三原色信号，RGB 色彩模式是工业界的一种颜色标准。它是通过对红（R）、绿（G）、蓝（B）三个颜色通道的变化以及它们相互之间的叠加来得到各式各样的颜色，目前应用广泛。

VGA的应用

目前来看，VGA可广泛应用于超市、车站、飞机场等公共场所的宣传和提示信息显示，也可应用于工厂车间生产过程中的操作信息显示。

3.DVI：

DVI的英文全名为：Digital Visual Interface，中文称为“数位视讯接口”。是一种视讯接口标准，设计的目标是透过数位化的传送来强化个人电脑显示器的画面品质。目前广泛应用于LCD、数位投影机等显示设备上。此标准由显示业界数家领导厂商所组成的论坛：“数位显示工作小组”(Digital Display Working Group，DDWG)制订。DVI接口可以传送未压缩的数位视频资料到显示装置。

DVI接口是以Silicon Image公司的 PanalLink接口技术为基础，基于TMDS (Transition Minimized Differential Signaling，最小化传输差分信号)电子协议作为基本电气连接。TMDS是一种微分信号机制，可以将象素数据编码，并通过串行连接传递。显卡产生的数字信号由发送器按照TMDS协议编码后通过TMDS通道发送给接收器，经过解码送给数字显示设备。

一个DVI显示系统包括一个传送器和一个接收器。传送器是信号的来源，可以内建在显卡芯片中，也可以以附加芯片的形式出现在显卡PCB上;而接收器则是显示器上的一块电路，它可以接受数字信号，将其解码并传递到数字显示电路中，通过这两者，显卡发出的信号成为显示器上的图象。

DVI接口分类：

DVI接头除包含DVI标准所规定的数位信号脚位之外也可包含传统类比讯号(VGA)的脚位，此设计是为了维持DVI的通用性以便不同形式的屏幕可以共用同一种连接线。随着实作功能的不同，DVI接头被分成三种类型

DVI-D(D= Digital ，仅传送数位讯号)：是数字信号接口，只能去接 DVI-D 接口的信号，接口上只有3排8列共24个针脚，其中右上角的一个针脚为空。不兼容模拟信号。

DVI-A(A= Analog ，仅传送类比讯号)：是模拟信号接口，只能去接 DVI-A 或者VGA 接口的信号。

DVI-I( I = A+D = Integrated ，可传送数位及类比讯号)：包含DVI-A和DVI-D两个接口，在管脚定义上有明显的区分，可同时兼容模拟和数字信号。兼容模拟信号并不意味着模拟信号的接口D-Sub接口可以连接在DVI-I接口上，而是必须通过一个转换接头才能使用，一般采用这种接口的显卡都会带有相关的转换接头。

当 DVI-I 接 VGA 时，就是起到了 DVI-A 的作用，当DVI-I 接DVI-D时，只起了 DVI-D 的作用。此外有实作出第二组DVI炼路的接头有时被称为DVI-DL (dual link).

某些较新型的DVD播放机，电视机(包括HDTV)以及投影机采用了所谓"DVI/HDCP"接头，这种接头在外型上完全与DVI相同，但是其传送的资料有经过HDCP协定所加密以防止非法复制。现今装有DVI接口显卡的电脑经常可利用前述显示装置作为大型屏幕之用，但由于2007年之前产制的显卡大多不支援HDCP，所以可能会受到版权保护技术的限制而无法以最高分辨率播放受到HDCP保护的视讯内容。

此外，DVI-D的类比脚位故意设计得比DVI-I的同样脚位短，以防止使用者将DVI-I公头误插入DVI-D的母座。

4.DP：

DisplayPort（简称DP）是第一个依赖数据包化数据传输技术的显示通信端口。是一个由PC及芯片制造商联盟开发，视频电子标准协会标准化的数字式视频接口标准。主要用于视频源与显示器等设备的连接，它既可以用于内部显示连接，也可以用于外部的显示连接。

DP接口有DP和mini DP两种接口

DP 版本区别：

1.1最高支持2560*1600 (2K）分辨率（已基本淘汰）

1.2最高支持4K（4096*2160）60Hz （最常用）

1.3最高支持4K（3840X2160）120hz、5K（5120X2880）60hz、8K（7680X4320）30hz输出。

1.4最高支持8K级别（7680x4320）的60Hz输出，4K的话则可以上到120Hz。（最新版本）

DP 接口特点：

DP作为传输带宽最高的数字信号传输，可同时传输音频信号，为未来发展趋势接口。

DP接口常见设备：智能电视，笔记本电脑，独立显卡，显示器。

DP接口作为DVI的继任者，DP将在传输视频信号的同时加入对高清音频信号传输的支持，同时支持更高的分辨率和刷新率。它能够支持单通道、单向、四线路连接，数据传输率10.8Gbps，同时还支持1Mbps的双向辅助通道，供设备控制之用，此外还支持8位和10位颜色。在数据传输上，DP使用了“micro-packetised”格式。VESA还表示，DP具备高度的可扩展性，可以在今后不断加入更多新内容。

从应用方面来看，DP接口能够传输视频和音频信号，并且在带宽方面十分出众。DP凭借着“免费”的特点相比HDMI而更占优势。

DP 接口优势

AMD多屏拼接技术必须要DP接口。AMD在显卡中，支持了AMD最新发布的多屏拼接显示技术。其中以三屏拼接为例，AMD的HD5000系列显卡上设计有DP接口，用户需要通过DP数据线与支持此接口的显示设备进行连接，成为三屏拼接显示的主显示器，并且必须是DP接口直接连接，不能经过任何形式的转换。因此对于显示发烧用户而言，它们对于能够支持DP接口的液晶显示器的需求逐渐的增加。

信号传输，DP接口能够传输10.8Gbps带宽的信号，凭借着超高的带宽优势，DP可以很轻松的支持2560×1600超高分辨率的显示。

DP 接口转接使用：

DP转HDMI可以实现双向转接，且传输画面不会失真。最常见的场景是从电脑到电视的转接，转接过程中可以分配多种模式操作。

镜面模式：电脑和电视显示同样的画面，实现从小屏到大屏的转变

扩展模式：一网多用模式，利用电脑和电视或投影之间的转接，使画面在电视或投影上进行播放，电脑可以进行其他操作

DP转DVI适用范围有：带有 DP接口的台式机/笔记本，连接到显示器/投影仪/电视。DP转DVI是单向转接，DP转DVI产品只能DP向DVI转换，DP端接电脑主机显卡，DVI接显示器，反过来用则没有显示。

DP转VGA，DP和VGA两种接口不能直接转接，转接器需要添加芯片，但是一般售卖转接器中都是加了芯片的，所以一般不用担心这个问题。

6.SDI：

SDI接口的简单说明

SDI接口，是"数字分量串行接口". SDI接口是数字分量串行接口(serial digital interface)的首字母缩写。

SDI接口是“数字分量串行接口”，而HD-SDI接口是广播级高清数字输入和输出端口，其中HD代表高清信号。由于SDI接口不能直接传输压缩的数字信号，因此必须解压缩数字视频录像机，硬盘和其他设备记录的压缩信号，并通过SDI接口输出才能进入SDI系统。

如果反复进行解压缩和压缩，将不可避免地导致图像质量下降和延迟增加。因此，各种格式的数字视频录像机和非线性编辑系统已经指定了它们自己的接口，用于直接传输压缩的数字信号。

在非编辑后期制作，广播电台等领域，HD-SDI被广泛使用。它基于SMPTE292M，SMPTE292M是用于在1.485Gb / s或1.485 / 1.001Gb / s信号速率下传输的接口规范。该规范指定了数据格式，通道编码方式，同轴电缆接口的信号规范，连接器和电缆类型以及光纤接口。 HD-SDI接口使用同轴电缆，而BNC接口用作电缆标准。有效距离为100M。

SDI串行接口是把数据字的各个比特以及相应的数据通过单一通道顺序传送的接口。由于串行数字信号的数据率很高，在传送前必须经过处理, 它属于数字基带信号。SMPTE组织在2015年正式发布了串行数据接口的6G-SDI和12G-SDI。6G-SDI面向2160p 30的应用，对应每秒30帧画面的刷新。而12G-SDI面向2160p 60（俗称真4K）的应用，对应着每秒60帧画面的刷新。

12G-SDI是面向2160p60（俗称真4K）的应用，bai12G-SDI可以将4根传输3G-SDI信号的线整合为一根，直接传输4K的音视频。对应着每秒60帧画面的刷新，有了12G-SDI，一根线可以解决4K的传输，这样，需要的线少了，系统也更加简单，画质也更有保障。而且，12G是向下兼容3G/HD/SD的，这样，接入现有的高清切换台等系统，也不成问题。