转载

谈HTTPRestAPI接口设计02(12.6)

在上篇文章主要谈了Http Rest接口设计的一些关键原则和设计规范要求等，这篇文章主要谈下基于Http Rest接口，我们在实施过程中如何通过一些工具支撑来进行接口设计的规范化和标准化问题。大家都知道，在采用传统的SOAP WebService服务接口的时候，由于SOAP WS服务本身有WSDL和XSD文件的强接口契约规范格式要求，因此很容易基于从顶向下，规范先行的思路来进行服务实施流程管控。即：

1. 先定义接口服务规范文档，当前我们通过Word文件进行定义。

2. 将Word文件定义的接口规范导入到管控系统中，形成结构化的服务元数据定义。

3. 基于服务规范定义来生成的标准WSDL和XSD文件

4. 将WSDL和XSD服务契约设计文件分发给业务系统，进行服务消费端和提供端的开发。

可以看到传统的WS服务实施下，我们可以通过规范和契约先行的方式很好的控制接口的标准化和一致性，同时大家遵循完全相同的一套WSDL文件进行接口的提供或开发，基本不存在接口实现中数据结构不一致的问题。

在采用RestAPI接口进行设计的时候，实际上仍然有一个关键点，就是设计要先行，先设计，然后再进行开发和测试，同时设计文件能给标准化和结构化，通过设计文件来生成相应的客户端和服务端代码框架，通过设计文件来生成相应的测试用例，通过设计文件来生成对应的API接口设计文档。

设计先行，是Http Rest接口服务实施中的一个关键点。

1. 设计工具的选择问题

当前两者主流的设计规范和建模语言，一个是RAML，一个是WADL。

RAML(RESTful API Modeling Language） 即 RESTful API 建模语言)是对 RESTful API的一种简单和直接的描述。它是一种让人们易于阅读并且能让机器对特定的文档能解析的语言。RAML 是基于 YAML,能帮助设计 RESTful API 和鼓励对API的发掘和重用,依靠标准和最佳实践从而编写更高质量的API。通过RAML定义,因为机器能够看得懂,所以可以衍生出一些附加的功能服务,像是解析并自动生成对应的客户端调用代码、服务端代码结构, API说明文档。

https://www.w3cschool.cn/web_api_next/qw2zpozt.html

https://raml.org/projects

https://www.cnblogs.com/softidea/p/5728952.html

WADL（Web Application Description Language） 是一种用于描述web应用对外提供接口语言，它使用XML来表示。其中主要包括每个资源的定位（URI）、请求类型（GET、POST等）、请求参数类型（路径参数、query参数等）、响应值和响应类型等一系列内容。根据这个XML，可以直接读取到系统提供的所有REST API，并能够进行调用。由于WADL使用XML描述，对于开发者来说，可以通过标准的xslt进行转换，将机器读取的XML转换成便于人读取的HTML，进而行程API文档。

https://coolex.info/blog/547.html

http://blog.chinaunix.net/uid-9789791-id-1997442.html

http://www.doc88.com/p-6661149184381.html

对应设计工具，这里只谈下Swagger设计工具，这个工具最大的好处就是只需要通过编辑器进行Rest接口设计文件的定义，然后可以自动生成测试框架，自动生成客户端和服务端多种语言下的开发框架，生成API接口设计文档，这个工具本身设计完成内容还可以导出为YAML文件或Json文件，也支撑文件导入。

https://swagger.io/tools/

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。Swagger的目标是对REST API定义一个标准的和语言无关的接口，可让人和计算机无需访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过Swagger进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger消除了调用服务时可能会有的猜测。

Swagger是一组开源项目，其中主要要项目如下：

Swagger-tools: 提供各种与Swagger进行集成和交互的工具。

Swagger-Editor: 编辑器，Swagger API Spec是Swagger用来描述Rest API的语言，

Swagger-core: 用于Java/Scala的的Swagger实现。

Swagger-js: 用于JavaScript的Swagger实现。

Swagger-node-express: Swagger模块，用于node.js的 Express web应用框架。

Swagger-ui： 一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。

Swagger API Spec包含以下部分内容，详细参考：

https://www.cnblogs.com/jpfss/p/8072443.html

注意通过Swagger-Editor编辑器可以完成整个接口的定义和接口设计工作，同时一方面用于客户端和服务端代码框架的生成，一方面用于帮助文档的生成。但是Swagger对于帮助文档的生成需要在代码框架里面增加注解，相对来说注解编写的工作量较大。这也是网上很多提到的文档生成方面Swagger往往并不是最佳选择。

原有的接口服务规范编写思路改进

对于原来的接口服务规范编写思路，可以看到几个改进或优化思路。

1. 还是保留先编写Word格式的接口服务规范，然后再将Word接口服务规范转为标准的YAML或WADL接口规范定义文件，同时再生产客户端或服务端的代码框架文件。

2. 抛弃Word编写规范模式，直接在类似Swagger编辑器中对接口文件进行设计，设计完成后发出文件进行评审和检查，没问题后由集成平台归档并导入管控生产服务规范，同时生成客户端和服务端代码框架一同下发。

现在发现的一个问题不好解决点在于，在进行接口文件设计的时候能否直接增加字段和数据项的中文描述和业务备注说明，该信息最终体现到生成的文档上。或者说我们需要通过YAML或Json文件，来逆向生成Word文档，然后Word文档再下发给业务系统补充中文描述信息。

2. API文档的生成

如果采用Swagger工具来进行API接口服务的设计，可以看到在编辑器里面，设计过程和文档生成过程基本是同步的，即一个API接口设计好后，文档基本就已经生成完成并可用。当前唯一发现的问题就是没有想过的中文描述，如果需要中文信息，还需要在代码框架里面增加注解，这个过程来说就想到繁琐了。

https://www.jianshu.com/p/0438034ee55f

SpringBoot项目生成RESTfull API的文档，第二篇给出SpringBoot和Swagger整合思路

https://www.jianshu.com/p/af7a6f29bf4f

http://blog.didispace.com/springbootswagger2/

https://gitee.com/didispace/SpringBoot-Learning

Wisdom REST Client

Wisdom RESTClient supports automated testing and automatically generating RESTful API document based on history cases. Wisdom RESTClient可以自动化测试RESTful API 接口，同时，基于测试过的历史数据，可以自动生成API文档。

工具地址： https://github.com/Wisdom-Projects/rest-client

这个工具是偏测试后的文档生成，最终生成的文档展现和Swagger展现效果类似。

Api2Doc文档生成工具

Api2Doc 专注于 Restful API 文档的自动生成，它的原理与 Swagger2 是类似的，都是通过反射，分析 Controller 中的信息生成文档，但它要比 Swagger2 好很多。最大的不同是： Api2Doc 比 Swagger2 要少写很多代码。

第一是对应注解过程本身更加简单，其次就是可以自动分析类引用，讲类定义中关于数据项的注释信息引用到最终生成的文档中，这个功能就相当好用了，很好的解决了我们前面提到的数据项中文描述的问题。

参考： http://blog.51cto.com/13613194/2090764

https://www.cnblogs.com/yoyotl/p/6376624.html

使用Asciidoc代替Markdown和Word撰写开发文档

Asciidoc是另外一个可以用于HttpRest接口文档生成的工具。该工具简洁而不简陋的语法，它专门为编写书籍而生，在语法的支持上很到位，但不像Word那样可以随性，可以让你的文档更统一美观。AsciidocFX工具开源跨平台，使用体验很不错，更可以导出HTML、PDF、EBook等格式

具体参考：https://my.oschina.net/gudaoxuri/blog/524132

http://houqp.github.io/wbwa/wbwa.html

感觉该工具完全可以用于帮助手册的制作。常用的列表，段落，超链接，图片，表格，代码等能力都支持。