缘由

最近项目要加新功能，回头看了下之前定义的接口文档，简直不忍直视。有用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。