缘由

最近项目要加新功能,回头看了下之前定义的接口文档,简直不忍直视。有用txt的、有用word的,各种格式不规范,写法也不一样,看起来很头疼。不够直观,并且也很难维护。想起之前同事分享过的Swagger,趁着最近不忙,就决定着手把之前的API文档整理到Swagger中去。


Swagger是什么

官方的介绍是 A POWERFUL INTERFACE TO YOUR API。

通过Swagger提供的相关tools可以很直观的在网页上浏览你的API、测试API、甚至通过解析Swagger definitions(一个YAML or JSON格式的文档),直接自动生成相关代码(swagger-codegen)。个人理解Swagger的核心就是Swagger definitions,相关工具可以(Swagger Core、Swagger Editor)生成Swagger definitions,(Swagger UI、Swagger Editor)解析Swagger definitions生成UI界面。


为什么要用Swagger

工具从来都是为了提高效率而产生的,想想从前光写个API文档都要花好些时间,而且其中还会出现理解上的偏差,需要前后端反复沟通确认,不仅浪费了时间还没有什么效率。通过使用Swagger,我们既可以用它来作为API的文档,也可以用来测试API,前端 or 客户端的同学通过对各个API的点击可以实时的看到返回结果,节约了大量的沟通时间,极大的提高了开发效率。


怎么用

Swagger Api 提供了如下工具来为我们服务:

  • Swagger Core [Java-related libraries for generating and reading Swagger definitions] 一个JAVA Lib,用来生成和解析Swagger definitions,没用过。。

  • Swagger Codegen [Command-line tool for generating both client and server side code from a Swagger definition] 据说可以通过它解析Swagger definitions生成对应的后端API实现代码,没用过。。

  • Swagger UI [Browser based UI for exploring a Swagger defined API] 通过解析定义好的Swagger definitions构建对应的API UI界面。 GitHub - Swagger UI。 GitHub里的说明基本都已经很详细了,这里就不多做介绍了。基本上只要你预先装好npm(node)和gulp,直接照着步骤就没什么问题。对应的demo - petstore.swagger.io,在这里可以看见构建好的应用的样子,也可以通过解析自己定义的Swagger definitions来查看自己定义的API,不过需要注意的是,基本上都会遇到跨域的问题,这里个人建议是把Swagger UI构建在自己的服务器上,这样就可以避免了。最后上张完成图。 swagger-ui-example

  • Swagger Editor [Browser based editor for authoring Swagger definitions in YAML or JSON format] 上面很多地方都提到了Swagger definitions,那究竟Swagger definitions要如何定义呢。Swagger Editor提供了web界面来帮我们编辑、生成(导出)对应的Swagger definitions,同时Swagger Editor也可以实时的解析编辑好的Swagger definitions,生成对应的UI界面(类似Swagger UI),不仅如此Swagger Editor还支持生成对应client code(总之是一个很强大的工具,基本上用它就能满足我们的需求了)

    同样的对应的GitHub - Swagger Editor,安装方式大同小异,线上demo - editor.swagger.io,同样的也会有跨域的问题。 swagger-editor-example


写在最后

关于具体的Swagger definitions如何定义就得参照官方文档了,我只用过一个enum参数,实现了请求参数的select选项。最后吐槽下,关于Swagger的基本上都是英文文档,中文资料较少,导致最后在实现自己需求时花费了不少时间,实际上仅仅是配一个参数就好了T T。