记得上次整合了swagger,感觉挺麻烦的。后来才得知已经有swagger2,上次辛辛苦苦配置的swagger已经是旧版本的了…
据说swagger2不仅功能更加强大,配置也更加简单。所以我马上就尝试整合了一下。
一、实现流程
(1)引入如下依赖
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
<dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-core</artifactId> <version>2.7.5</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version>2.7.5</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-annotations</artifactId> <version>2.7.5</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.5.0</version> </dependency> |
需要jackson的相关依赖,还有最为核心的springfox-swagger2这个包。
(2)写两个配置类
先新建一个com.xie.swagger包,然后写入如下两个类:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 |
package com.xie.swagger; import static springfox.documentation.builders.PathSelectors.regex; import java.util.Date; import javax.servlet.http.HttpSession; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.http.ResponseEntity; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 public class swaggerconfig { // 处理的地址 public static final String DEFAULT_INCLUDE_PATTERN = "/.*"; @Bean public Docket testApi() { Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(testApiInfo()).forCodeGeneration(true).genericModelSubstitutes(ResponseEntity.class).ignoredParameterTypes(pageinfo.class).ignoredParameterTypes(HttpSession.class).ignoredParameterTypes(java.sql.Date.class).directModelSubstitute(java.time.LocalDate.class, java.sql.Date.class) .directModelSubstitute(java.time.ZonedDateTime.class, Date.class).directModelSubstitute(java.time.LocalDateTime.class, Date.class).select().paths(regex(DEFAULT_INCLUDE_PATTERN)).build(); return docket; } private ApiInfo testApiInfo() { Contact contact = new Contact("....", ....", "...."); ApiInfo apiInfo = new ApiInfo("....", // 大标题 "....", // 小标题 "....", // 版本 "....", contact, // 作者 "....", // 链接显示文字 "...."// 网站链接 ); return apiInfo; } } |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
package com.xie.swagger; public class pageinfo { // 当前页 int pageNum; // 页面显示数目 int pageSize; public int getPageNum() { return pageNum; } public void setPageNum(int pageNum) { this.pageNum = pageNum; } public int getPageSize() { return pageSize; } public void setPageSize(int pageSize) { this.pageSize = pageSize; } } |
(3)把这个swaggerconfig类放进spring mvc中进行整合
把这个类注入到spring容器中。
注意:一定要在spring-mvc.xml文件中进行配置
1 |
<bean class="com.xie.swagger.swaggerconfig" /> |
如果写在spring.xml中,可能会报错。
(4)下载swagger-ui组件,放入webapp目录
下载地址:https://github.com/swagger-api/swagger-ui
下载完之后,新建一个swagger文件夹,把dist里面的文件丢进去。
很重要的一步:
修改swagger/index.html文件,默认是从连接http://petstore.swagger.io/v2/swagger.json获取api的json,这里需要将url值修改为http://{ip}:{port}/{projectName}/v2/api-docs的形式,{}中的值根据自身情况填写。
注意:这里不同于上一篇文章,这里的路径中有一个v2,千万别漏。/v2/api-docs都是不能改动的,如果改动就获取不到json了。
(5)允许静态资源访问
因为swagger-ui需要多种静态资源的支持,包括html,css,js,所以有必要配置静态资源的直接访问。
这个方法就多种多样了。
- 可以在web.xml中配置<servlet-mapping></servlet-mapping>
- 也可以在spring-mvc.xml中配置<mvc:resources location=”” mapping=””></mvc:resources>
我采取的是第一种方式:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 |
<servlet-mapping> <servlet-name>default</servlet-name> <url-pattern>*.html</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>default</servlet-name> <url-pattern>*.js</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>default</servlet-name> <url-pattern>*.css</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>default</servlet-name> <url-pattern>*.png</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>default</servlet-name> <url-pattern>*.jpg</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>default</servlet-name> <url-pattern>*.img</url-pattern> </servlet-mapping> |
(6)注释你的controller
默认注释为@ApiOperation(value = “***”)
这样你的这个接口就会在index.html中标示出来了。
还有更多的配置,在以后将会提及。
(7)实现效果
二、总结
比较要注意的地方是那个v2,总体来说整个配置流程是很简单的。实现的效果也很不错。