SpringFox 初体验

达芬奇密码2018-07-25 12:35

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/

本文来自网易实践者社区,经作者郑勤授权发布。