SpringMVC+Swagger2整合(springfox-swagger)

一、前言

Swagger是一款RESTFUL接口文档在线自动生成+功能测试的工具软件。Swagger是一个规范和完整的框架,用于生成、描述、调用和可视RESTFul风格的Web服务
springfox-swagger是用于用Spring构建API的自动JSON API文档的开源工具集合,可以让开发者快速的将swagger集成到项目中。此外如果不单独部署swagger,可以使用springfox-swagger-ui集成到项目中。

二、项目引入依赖

此处我们使用maven进行项目管理,去 https://mvnrepository.com 搜索springfox-swagger,会看到Springfox Swagger2Springfox Swagger Ui,我们使用最新的2.7.0版本,获取对应的pom.xml配置,如下:

注意: spring版本依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>

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

启动时会报错,提示找不到 com.fasterxml.jackson.core.jackson-databind,需要加入依赖

<dependency>
       <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-databind</artifactId>
      <version>2.6.6</version>
</dependency>

三、配置

配置部分主要分两部分,第一是Swagger的配置,即项目启动的时候需要读取到相应的配置来加载swagger并扫描形成文档,另外可以根据运行环境来决定是否启用swagger扫描。

1. swagger配置
// WebAppConfig.java
package com.web.swagger2;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;

import springfox.documentation.builders.ApiInfoBuilder;
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
@EnableWebMvc
@ComponentScan(basePackages = {"com.web.api", "com.web.controller"}) // 扫描路径
public class WebAppConfig {
    
    @Bean
    public Docket customDocket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }
    
    /**
     * 接口描述信息
     * @return
     */
    private ApiInfo apiInfo() {
        Contact contact = new Contact("后台接口", "http://www.test.com", "xxx@123.com");
        return new ApiInfoBuilder()
            .contact(contact)
            .title("系统API接口")
            .description("系统API接口")
            .version("3.0.0")
            .build();
    }
}

2. spring配置

这里需要注意两个地方,首先要支持/v2/api-docs的路径,如果被拦截则不能返回正确的文档json;其次如果项目中做了权限控制,也需要对swagger的相关路径进行放行。

  • 设置web.xml
<servlet-mapping>
    <servlet-name>springServlet</servlet-name>
    <url-pattern>/*</url-pattern>   // 这里需要支持/v2/api-docs路径
  </servlet-mapping>
  • 设置spring-mvc.xml
<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"/>
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>

四、控制器以及注解

控制器(@Controller)只要在扫描路径中(@ComponentScan),不需要任何配置,就已经会被springfox-swagger识别了,下面的例子是简单的控制器。

@Controller
@RequestMapping("/test")
public class TestController {
    @ApiOperation(value="一个测试API",notes = "第一个测试api")
    @ResponseBody
    @RequestMapping(value = "/hello",method = RequestMethod.GET)
    public String hello()
    {
        return "hello";
    }
}

注解 请参考 http://springfox.github.io/springfox/javadoc/current/,以下为主要常用的注解:

  • @ApiIgnore 忽略注解标注的类或者方法,不添加到API文档中

  • @ApiOperation 展示每个API基本信息

  value api名称
  notes 备注说明
  • @ApiImplicitParam 用于规定接收参数类型、名称、是否必须等信息
name 对应方法中接收参数名称
value 备注说明
required 是否必须 boolean
paramType 参数类型 body、path、query、header、form中的一种 
body 使用@RequestBody接收数据 POST有效
path 在url中配置{}的参数
query 普通查询参数 例如 ?query=q ,jquery ajax中data设置的值也可以,例如 {query:”q”},springMVC中不需要添加注解接收
header 使用@RequestHeader接收数据
form 笔者未使用,请查看官方API文档
dataType 数据类型,如果类型名称相同,请指定全路径,例如 dataType = “java.util.Date”,springfox会自动根据类型生成模型
  • @ApiImplicitParams 包含多个@ApiImplicitParam

  • @ApiModelProperty 对模型中属性添加说明,例如 上面的PageInfoBeen、BlogArticleBeen这两个类中使用,只能使用在类中。

 value 参数名称
 required 是否必须 boolean
 hidden 是否隐藏 boolean 
  • @ApiParam 对单独某个参数进行说明,使用在类中或者controller方法中都可以。注解中的属性和上面列出的同名属性作用相同

五、查看文档

项目启动后可以访问 http://localhost:8080/v2/api-docs, 这个接口返回json格式的接口文档信息。

访问http://localhost:8080/swagger-ui.html 可以查看文档

由于我直接使用的正式项目做的配置,这里就不做截图了,大家可以自行体验。

如有任何问题和建议,可留言。

推荐阅读更多精彩内容

  • Spring Boot 参考指南 介绍 转载自:https://www.gitbook.com/book/qbgb...
    毛宇鹏阅读 43,878评论 6 343
  • Spring Cloud为开发人员提供了快速构建分布式系统中一些常见模式的工具(例如配置管理,服务发现,断路器,智...
    卡卡罗2017阅读 130,464评论 18 138
  • Android 自定义View的各种姿势1 Activity的显示之ViewRootImpl详解 Activity...
    passiontim阅读 165,874评论 24 701
  • 刚刚经历了考研一切的人生好像从头开始,后来很多的烦恼,很多的担忧不知道未来在哪里十分迷茫,未来很远。来日方长~
    糖果罐558阅读 85评论 0 0
  • 帘外细碎的锄地声撩拨人心 在冬夜里 突然想背弃暖和的被褥 去梦梦里的头发被高海拔的风掀起 爬起来从窗帘缝偷看 邻居...
    丁千阅读 158评论 2 0
  • 感赏今天上了个早班,可以早点回家休息。因为昨天帮朋友代班站了一天,累死了。今天正好下了早班,好好休息啦。 感赏今天...
    离不若阅读 105评论 0 0
  • 近日,阿里巴巴发布了天猫精灵K1和AliGenie开发者平台,强势杀入国内的智能音箱市场。其实在之前京东就和叮咚智...
    是小岸阅读 235评论 0 2