美文网首页
SpringMVC+Swagger2整合(springfox-s

SpringMVC+Swagger2整合(springfox-s

作者: JimmyGan | 来源:发表于2017-09-07 15:12 被阅读0次

一、前言

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 可以查看文档

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

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

相关文章

网友评论

      本文标题:SpringMVC+Swagger2整合(springfox-s

      本文链接:https://www.haomeiwen.com/subject/qsqijxtx.html