SpringFox 初体验

本文来自网易云社区。

1、什么是SpringFox？

1.1 Springfox

是一个开源的API Doc的框架， 它的前身是swagger-springmvc，可以将我们的Controller中的方法以文档的形式展现。官方定义为： Automated JSON API documentation for API's built with Spring。

1.2 Swagger

那Swagger又是什么哩？ 官方说法：Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

2、SpringFox能做什么？

• 首先、使前端和后端更加解耦，前后端的对接通常是API形式，而后端开发人员在开发的过程中，提供的API和描述文档却是难以同步的，往往是开发代码完成了，但文档描述并不及时，甚至会忘记这一环节，导致前端调用API时经常发生错误，因此，springfox应运而生，它将前后端有效分离，并保证了API与文档的实时同步；
• 其次、使用springfox生成的接口文档直观可视，也帮助后端开发人员脱离了写接口文档的痛苦，及避免不厌其烦的解说各个接口需要的参数和返回结果；
• 再次、springfox支持在线测试，可实时检查参数和返回值。

3、怎么使用SpringFox?

现在，基于maven框架创建一个简单的springmvc项目，并以此为例来说明下springfox的使用。

3.1 基本依赖

springfox目前最新版本是2.6.1，在pom.xml中引入如下2个包

<dependency>    <groupId>io.springfox</groupId>    <artifactId>springfox-swagger2</artifactId>    <version>2.6.1</version></dependency><dependency>    <groupId>io.springfox</groupId>    <artifactId>springfox-swagger-ui</artifactId>    <version>2.6.1</version></dependency>

同时、因为swagger需要jackson支持，故pom.xml中也要引入jackson关联的包，当前最新版本是2.8.6

<!--jackson用于将springfox返回的文档对象转换成JSON字符串 --><dependency>    <groupId>com.fasterxml.jackson.core</groupId>    <artifactId>jackson-annotations</artifactId>    <version>2.8.6</version></dependency><dependency>    <groupId>com.fasterxml.jackson.core</groupId>    <artifactId>jackson-databind</artifactId>    <version>2.8.6</version></dependency><dependency>    <groupId>com.fasterxml.jackson.core</groupId>    <artifactId>jackson-core</artifactId>    <version>2.8.6</version></dependency>

3.2 一个简单的springmvc项目

1、如图所示，一个简单的springmvc项目结构：

2、web.xml配置文件如下：

3、springfox-test-servlet.xml配置文件如下：

4、swagger配置类SwaggerApiConfig.java, 在这里可以设置swaggerUI的页面个性信息、加载类的过滤等，如图示例：

5、最后，在Controller类中添加springfox注解

6、以上配置无误的话，将项目放入Tomcat中启动(或用maven的集成tomcat插件亦可)，访问页面地址http://localhost:8088/springfox-test/swagger-ui.html，将会出现如下页面。

7、展开这个接口，可以看到页面清晰，说明详细，而且还可以测试哦

以及 try it out!

4、参考文献

springfox

1. 官网： http://springfox.github.io/springfox/
2. 使用说明：http://springfox.github.io/springfox/docs/current/

本文来自网易云社区，经作者郑勤授权发布。

原文： SpringFox 初体验

网易云新用户大礼包：https://www.163yun.com/gift

更多网易研发、产品、运营经验分享请访问网易云社区。