接口描述的工具有很多,比较知名的 Swagger和 Raml,我个人更倾向于 Raml 。 ? raml-mocker raml-mocker (https://github.com/xbl/raml-mocker) 是一个基于 Raml 使用 Nodejs 开发的 Mock Server 工具 ,使用 Raml 描述接口中设置 response 的 example 指令即可,raml-mocker 会解析 Raml 文件,并启动一个 Mock Server,将 example 的内容返回给浏览器 开始、初始化项目 git clone https://github.com/xbl/raml-mocker-starter.git raml-api cd raml-api git remote rm raml: raml 文件目录 main: raml 目录下的入口文件 port: mock server 服务端口号 plugins: 插件 入门篇:Mock Server raml-mocker
然而,RAML 的采用率不如 OpenAPI 广泛。虽然 RAML 有一个专门的社区,但它的社区支持较少。RAML 有工具,但有一些迹象表明最新版本缺乏必要的支持。 RAML 的层次结构可能更适合作为设计和规划工具。因此,RAML 可能比 REST 更支持 “规范优先” 的方法。 最终,RAML 被营销一种为了 “数据建模” 和 “API 描述” 工具,而Swagger 则仅是后者。下一节将更详细地讨论 RAML 的层次模型。 接下来我们将更详细地讨论 RAML 的类型系统。不支持数据模型继承RAML 的对象类型可以继承其他对象类型。虽然 OpenAPI 模式可以“引用”其他模式,但它并不像 RAML 那样在技术上支持继承。 而 RAML 则更进一步。你可以在数据模型之间建立关系,并避免共享属性的重复。使用 OpenAPI,模式不会像 RAML 那样以层次化的方式相互关联。
接口描述的工具有很多,比较知名的 Swagger 和 Raml,我个人更倾向于 Raml 。 ? raml-mocker raml-mocker 是一个基于 Raml 使用 Nodejs 开发的 Mock Server 工具,使用 Raml 描述接口中设置 response 的 example 指令即可 ,raml-mocker 会解析 Raml 文件,并启动一个 Mock Server,将 example 的内容返回给浏览器。 此功能使用了raml2html。 配置 .raml-config.json ? controller: controller 目录路径,在高级篇中会有更详细说明 raml: raml 文件目录 main: raml 目录下的入口文件 port: mock server 服务端口号
接口描述的工具有很多,比较知名的 Swagger 和 Raml,我个人更倾向于 Raml 。 ? raml-mocker raml-mocker 是一个基于 Raml 使用 Nodejs 开发的 Mock Server 工具,使用 Raml 描述接口中设置 response 的 example 指令即可 ,raml-mocker 会解析 Raml 文件,并启动一个 Mock Server,将 example 的内容返回给浏览器。 此功能使用了raml2html。 配置 .raml-config.json ? controller: controller 目录路径,在高级篇中会有更详细说明 raml: raml 文件目录 main: raml 目录下的入口文件 port: mock server 服务端口号
接口描述的工具有很多,比较知名的 Swagger 和 Raml,我个人更倾向于 Raml 。 ? raml-mocker raml-mocker (https://github.com/xbl/raml-mocker) 是一个基于 Raml 使用 Nodejs 开发的 Mock Server 工具, 使用 Raml 描述接口中设置 response 的 example 指令即可,raml-mocker 会解析 Raml 文件,并启动一个 Mock Server,将 example 的内容返回给浏览器 开始 初始化项目 git clone https://github.com/xbl/raml-mocker-starter.git raml-api cd raml-api git remote rm raml: raml 文件目录 main: raml 目录下的入口文件 port: mock server 服务端口号 plugins: 插件 入门篇:Mock Server raml-mocker
接口描述的工具有很多,比较知名的 Swagger 和 Raml,我个人更倾向于 Raml 。 raml-mocker raml-mocker 是一个基于 Raml 使用 Nodejs 开发的 Mock Server 工具,使用 Raml 描述接口中设置 response 的 example 指令即可 ,raml-mocker 会解析 Raml 文件,并启动一个 Mock Server,将 example 的内容返回给浏览器。 配置 .raml-config.json controller: controller 目录路径,在高级篇中会有更详细说明 raml: raml 文件目录 main: raml 目录下的入口文件 port 高级篇:动态 Server 如果静态的 Mock 数据不能满足你的需求,Raml-mocker 还提供了动态的功能。
接口描述的工具有很多,比较知名的 Swagger 和 Raml,我个人更倾向于 Raml 。 ? raml-mocker raml-mocker 是一个基于 Raml 使用 Nodejs 开发的 Mock Server 工具,使用 Raml 描述接口中设置 response 的 example 指令即可 ,raml-mocker 会解析 Raml 文件,并启动一个 Mock Server,将 example 的内容返回给浏览器。 此功能使用了raml2html。 配置 .raml-config.json ? controller: controller 目录路径,在高级篇中会有更详细说明 raml: raml 文件目录 main: raml 目录下的入口文件 port: mock server 服务端口号
RAML RESTful API建模语言(RAML)是一种旨在描述RESTful API的语言。 RAML是用YAML人类可读的数据串行化语言编写的。 下面是一个基于Java和JAX-RS框架的RAML的例子: ? 使用RAML进行JAX-RS框架,Java接口也可以生成RAML文件,这也为RAML规范提供了另一个选择。 API控制台,RAML到HTML和RAML2HTML等工具可以提供快速简单的方法来公开标准化文档,这些标准化文档可以在企业内部网中保密或可供公众使用。 第三方工具:Oracle和MuleSoft将RAML功能包含在其工具集中,以便通过粘贴规范来提供连接到使用RAML的任何API的能力。 RAML 0.8 v 1.0 RAML规范0.8仍然是目前的标准,但版本1.0在2016年9月开始获得势头。版本1.0包括以下更新。
奖励增强最大似然(RAML) RAML 最初用于将特定任务的 reward(task metric reward)纳入 MLE 训练,该方法相对于原版 MLE 有很大的性能提升。 具体来说,RAML 引入了一个指数 reward 分布 e(y|y*) ∝ exp{R(y|y*)},其中 R 指任务度量(如 BLEU)。RAML 最大化以下目标函数: ? 其效果本质上等同于 RAML 算法,区别在于 RAML 基于任务奖励函数来扩展探索空间。 Softmax 策略梯度 (SPG) SPG 旨在适应原版策略梯度,用作采样的奖励函数。 奖励增强最大似然(RAML) 如果用 MLE δ 奖励取代 e(y|y*) 中的任务奖励 R,则 RAML 目标函数就将等同于原版 MLE 目标函数。 MLE 和 RAML 之间的这种关系在 ERPO 中仍然存在。
库依赖冲突问题:Detected both log4j-over-slf4j.jar AND bound slf4j-log4j12.jar on the class path 问题描述 引入第三方库'org.raml :raml-parser:0.8.12',导致slf4j依赖冲突。 groupId>log4j</groupId> <artifactId>log4j</artifactId> </exclusion> </exclusions> Gradle: compile('org.raml :raml-parser:0.8.12'){ exclude module: 'slf4j-log4j12' exclude module: 'log4j' } 参考资料
Swagger、Apiary、RAML的格式各自采取了一种略有不同的设计方式,但在本质上都提供了相同的基本特性:以多种不同级别的细节对Web API进行描述。 以Swagger23为例,分为5个部分(示例图来自于RAML,不过功能都差不多)。 RAML使用RAML1.0标准,没有自己的可视化在线开发平台,而是用官方或第三方的离线工具(如API Workbench系列)来代替,因此它也存在一些缺点,比如:工具更新不及时,某些Tool不支持最新的 RAML1.0。 Reference Swagger:Rest API的描述语言 RAML vs. Swagger vs.
目前比较流行的 API 接口设计工具有 swagger,API blueprint 和 RAML。 它们共同的特点是你可以很方便地描述 API 的输入输出,并生成交互式的 API 文档。 RAML RAML 使用 yaml 来描述 API。它被设计地很灵活,很容易把描述分解到多个文件里然后相互引用。 ? 就描述语言来说,RAML 像是一个蓬勃向上的少年,精明而干练;而 swagger 已经垂垂老矣,冗长而乏味。 我一开始在 RAML 和 swagger 两者间左右摇摆,写了不少测试代码,如果不是 swagger 的工具链过于吸引人,而 RAML 1.0 版本还处在 beta 阶段,我可能会最终选择 RAML。
groupId>log4j</groupId> <artifactId>log4j</artifactId> </exclusion> </exclusions> Gradle: compile('org.raml :raml-parser:0.8.12'){ exclude module: 'slf4j-log4j12' exclude module: 'log4j' }
(该想法受到奖励增强最大似然(RAML,Norouzi et al., 2016)的启发。) 与其他使用强化学习训练方法的文本 GAN 相比,ARAML 模型从平稳分布(而不是生成器分布)中获取样本,使用 RAML 训练范式(而不是策略梯度)优化生成器。 该研究受 RAML 的启发,提出了一种指数回报分布(exponential payoff distribution)——将强化学习损失和 RAML 损失结合起来。最终的损失函数如下所示: ?
基于 RAML 的接口定义、文档生成、Mock Server 完成了定义和使用的分离,通过一套规范完成的接口定义,可以用不同的工具得到适应不同API管理系统的输出,有更多的可能性,同时保持了核心定义不变 RAP 较之于 RAML,前者更加集中,所有的定义、文档、mock 都在同一个服务中完成,并且实时生效,方便快捷,如果只考虑方便易用,RAP 是更好的选择,而 RAML 显得更加繁琐,更适合于公开的接口定义
Creating a custom ConfigurationProvider in ASP.NET Core to parse YAML MuleSoft开源用于设计RESTful APIs的工具RAML Tools RAML的强大功能
使用 RAML 契约 使用 Swagger Yaml 契约或者 Pact 契约都能在一定程度上完成契约测试、生成文档、mock 等工作,但是我们在实际工作中发现这些工具和平台的契约规则并不相同。 好在业界早已认识到这个问题,于是一些组织提出了 RestFul API 统一建模语言 (RESTful API Modeling Language),也就是 RAML。 围绕着 RAML 这一标准,构建出 API 协作的工具链,设计、构建、测试、文档、共享。 ? 附录:API 文档工具清单 使用或调研过的,API 文档/契约生成工具 apidoc swagger blue sprint RAML 使用或调研过得 mock 工具清单 wiremock json-server
算法细节介绍 对于RAML,奖励函数基于TD-IDF匹配,即每个单词的词频与逆文档频率乘积的和除以长度。其基本原理是激励模型在其生成代中包含关键内容词。 根据经验,我们观察到,即使没有提高,有上述奖励的RAML也能比MLE基线产生更好的反应。温度参数τ是0.1。 为了近似RAML目标中的期望项,在开始时,从训练数据中为每个消息-响应对选择三个附加的激励最高的响应。为了进行公平的比较,我们不会在下面的迭代中采样新的响应。
电影服务的 API 将具有以下 RAML 规范: #%RAML 1.0 title: cinema version: v1 baseUri: / types: Movie: properties { Collection: {item : MoviePremieres } } /{id}: type: { Collection: {item : Movie } } 如果不了解 RAML api.get('/movies/premiers') .expect(200, done) }) }) 总结 创建了用于查询电影院正在上映的电影的 movies 服务,使用 RAML
目前Postman可以支持Swagger、RAML等格式,使用它你不需要学习开发语言,同时提供了类似测试suite、预期结果和检查等的功能。 除了免费部分,还提供了一些团队的专业版本。