SpringFox 自动生成JSON API文档

SpringFox 自动生成API文档

序

其实作者一直在思考一个问题，就是对于英文官方文档的阅读。现在和技术相关的许多问题，直接在百度或者Google上一搜，许多博客帖子就出来了。那么还有没有必要去看英文文档呢？很多博客只是写了这个问题是如何解决的，但是并没有写出他是如何找到这个问题的解决方法的。授人以鱼，不如授人以渔。这一文集的文章我将尽量采取从官方文档上找出技术问题的解决方案。记录自己使用官方文档的方式，以及分析解决技术问题的思路过程。并将他们分享给大家，作为一个参考。

正文

SpringFox是什么？

了解一个新的框架，或者技术我首先是看看它有没有官网，如果没有，那么就去githu这类开源社区上找。这里在百度上一搜就搜到了SpringFox的官网：http://springfox.github.io/springfox/
进入官网，标题已经很醒目的告诉了我们，SpringFox是一个什么东东。

SpringFox官网标题

Automated JSON API documentation for API's built with Spring大致意思就是说，为spring自动生成相关的JSON API文档。如果还是不太清楚，那么就进入下方的官方文档，看看它的Introduction。

SpringFox文档.png

拿到一个技术官方文档，由于有些文档很长，所以我们应该首先快速浏览一下它的目录，快速锁定对我们有用的部分。我不建议一上来就细读官方文档，这对于学习一个新的技术来说，只会分散注意力，首先我们走马观花的快速浏览一遍，注重看文档中总结概括性的内容。
这里我们的问题是想知道SpringFox到底是有什么用，所以在目录中我们发现了Introduction，这就是在介绍这个框架的用途。

The Springfox suite of java libraries are all about automating the 
generation of machine and human readable specifications for JSON 
APIs written using the spring family of projects. Springfox works by 
examining an application, once, at runtime to infer API semantics based 
on spring configurations, class structure and various compile time java 
Annotations.

这一段话，详细的描述了SpringFox的作用。就是利用注解、spring式配置，类来为后台应用接口生成可读的JSON API文档。

再到后面就可以根据文档中的Getting Started和Quick Start guides来进行快速部署这个应用了，在Start guides中有许多的配置，这里我们只需有个大概了解，到了需要的时候再来查阅配置信息即可。

如果我们相对这个框架的整体结构想要有所了解，可以去看第四节Architecture，在第五我们阅读章节头就会发现Spring Fox支持swagger的文档规范。那么Swagger有是什么？这里可以根据文档中的链接点击进去查看。然后继续往下读，可以发现其中用于编写文档的注解，其实是由Swagger-Core实现的。点击文档中的连接，我们就进入到了Swagger-Core所提供的API讲解的文档，使用这些API在利用SpringFox我们就能自动生成一个很不错的API文档啦。

本次介绍到此结束。主要还是在于对如何利用官方文档的探索。