API代码自动化生成

日期:2015-12-25作者:Brad Irby翻译:崔婧雯 来源:TechTarget中国 英文

API开发   API自动化   

【TechTarget中国原创】

API已经非常流行,但是开发人员在缺少文档,以及产品经理需求不完整的时候,要想生成API代码任然是件痛苦的事情。本文探讨Swagger如何在应用创建的流程里,帮助保证代码和文档的一致性。

我们都认同API很好这一点,但是它的构建过程很痛苦。需要跟踪很多细节,在产品经理的想法变成文档规范,再变成开发人员代码的过程中,这些细节很容易就乱成一团。我们无法帮助改善文档环节(除非项目经理会写代码),但是如果使用Swagger的话,保持文档和代码的同步会很容易。

Swagger是一个工具,能够让任何拥有合适技术能力的人定义API,生成文档,并且甚至生成支持该API的代码。使用在线Swagger编辑器,你可以使用YAML设计API,这是一种人类可读的类似XML的语言。通过键入映射到部分URL的字符串,来定义端点(称为路径)。然后定义输入参数和输出数据的类型,想要实现的安全特性,然后就可以了。

用户可以查看的Swagger编辑器的一个示例是Instagram API(图1)。(如果你进入编辑器,选择File -> Open Example,还可以选择其他一些示例。)

图1. Swagger查看Instagram API代码

图1中的其他数据中,可以看到定义了八个路径(路径以单引号开头,点击行号后面的小的钻石图标,可以展开该节点以便查看细节)。打开这些路径的其中一个(图2),就可以看到其要求的GET HTTP动词。可以阅读描述,看到它要求三个参数。如果调用成功(响应为200),它就会返回一个对象数组,在最下面的Media定义部分定义。

API代码自动生成

图2.查看定义路径之一

类似得,可以打开Media的定义,查看该对象的属性细节,包括嵌入的对象(图3只显示了Media定义的一部分)。

API代码自动生成

图3. Media定义的部分视图

使用Swagger编辑器定义API很方便,但是它并不比其他工具更加容易。但是,在编辑器的右边栏,会自动生成所描述的API的HTML文档(图4)。文档很完整,易于阅读,并且提供了所描述API调用的尝试方式。点击底部的“Try this operation(试试该方法)”按钮,允许用户输入参数,发起调用,并且查看结果。

API代码自动生成

图4.自动生成的文档

这些特性都让这个工具很有用。使用Generate Server和Generate Client菜单选项(图5),能够以你喜欢的任意语言生成代码,从而提供或者消费该API。这个代码生成工具本身就能够帮助用户节约很多枯燥的编程时间,更不用说在API生命周期里做出很多变更时能够带给大家的帮助。另外,在使用导出功能创建本地文本文件时,整个流程完美得契合源代码控制策略。用户还可以发布文件,这样其他开发人员能够和你的数据轻松集成。

API代码自动生成

图5.使用Generate Server和Generate Client选项

编写API代码很有必要但是也很费时。使用Swagger设计API并且发布YAML能够让这个过程对于内部开发人员,以及想要消费你的数据的开发人员的工作更加简单。

我们一直都在努力坚持原创.......请不要一声不吭,就悄悄拿走。

我原创,你原创,我们的内容世界才会更加精彩!

【所有原创内容版权均属TechTarget,欢迎大家转发分享。但未经授权,严禁任何媒体(平面媒体、网络媒体、自媒体等)以及微信公众号复制、转载、摘编或以其他方式进行使用。】

微信公众号

TechTarget微信公众号二维码

TechTarget

官方微博

TechTarget中国官方微博二维码

TechTarget中国

评论
查看更多评论

敬请读者发表评论,本站保留删除与本文无关和不雅评论的权力。

作者>更多

Brad Irby
Brad Irby

Brad Irby has been a developer and systems architect since 1990, designing and implementing systems using the Microsoft stack.

API>更多

  • API项目中 官方客户端不再是可有可无的

    在API项目中,有官方支持的客户端才能给API社区传达积极的信息。没有官方支持客户的API就像是没有方向盘的汽车。可能是辆好车,但是却哪儿也去不了。

  • Google收购Apigee,焦点在于企业本身还是API?

    Axway的Suraj Kumar认为Apigee收购案不一定是件好事。尽管Google也许会像Borg一样行动,这也许预示着Google的态度需要转变。

  • Google的新收购是否意味着API变得更酷了?

    Google对API管理解决方案提供商Apigee的收购,我们应该怎么评价呢?是为了打造一个改变游戏的联盟吗?或者只是技术巨头想尽快吞食市场份额的尝试?

  • 如何创建成功的RESTful API设计

    设计好的API是一项困难的任务,存在很多主观指标。哪怕是完全拥抱RESTfulAPI设计并对其问题域拥有完整视图的小型初创企业最终也会出现命名不一致、界面模糊以及无记录语义等问题。

相关推荐

技术手册>更多

  • BPM项目错误规避指南

    业务与技术的交叉点正是BPM关注的焦点,这也是大多数重大IT问题出现的地方,通过为业务分析员和软件开发人员提供通用的工具,BPM有希望使应用集成发生革命性变化。正因为这样,技术不能够单独支撑BPM的全部内容,也不能单独解决业务流程的所有问题。业务是BPM依托的另一方面。但是企业在进行BPM项目时却会遭遇种种问题,而有些问题是可以通过前期工作避免的,本期TT SOA技术手册介绍如何合理规避BPM项目中的错误,同时提供BPM技巧和工具信息。

  • SOA中间件最大化大数据价值指南

    对于技术专业人员,管理大数据已经越来越重要。研究表明,越来越多的组织开始处理大数据,但即使是有多年的经验的工作人员,也会造成很多麻烦。

  • 业务流程管理BPM(更新版)

    业务流程管理(business process management,bpm)不是一个新概念,甚至不是一个新名词。它是从相关的业务流程变革领域,如业务流程改进(bpi)、业务流程重组(bpr)、业务流程革新中发展起来的。流程管理技术也是从早期的工作流管理、eai、流程自动化、流程集成、流程建模、流程优化等技术中发展起来的。

  • 简单对象访问协议SOAP学习手册

    SOAP是一种简单的基于XML的协议,它使应用程序通过HTTP来交换信息。在我们的SOAP学习手册中,你将了解到什么是SOAP,以及它如何在应用程序之间交换信息。

TechTarget

最新资源
  • 安全
  • 存储
  • CIO
  • 数据库
  • 服务器
  • 云计算