SpringMVC集成Swagger2详解

随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、先后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要，swagger就是一款让你更好的书写API文档的框架。

Swagger能成为最受欢迎的REST APIs文档生成工具之一，有以下几个原因：
    Swagger 可以生成一个具有互动性的API控制台，开发者可以用来快速学习和尝试API。
    Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现。
    Swagger 文件可以在许多不同的平台上从代码注释中自动生成。
    Swagger 有一个强大的社区，里面有许多强悍的贡献者。
    Swagger 文档提供了一个方法，使我们可以用指定的 JSON 或者 YAML 摘要来描述你的 API，包括了比如 NAMES、ORDER 等 API 信息。

你可以通过一个文本编辑器来编辑 Swagger 文件，或者你也可以从你的代码注释中自动生成。各种工具都可以使用 Swagger 文件来生成互动的 API 文档。

一、pom.xml引入基于maven的swagger依赖

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

二、编写SwaggerConfig配置类

package com.foriseland.fsoa.pay.swagger;

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.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
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.foriseland.fsoa.pay.controller"})
public class SwaggerConfig {
	 @Bean
	    public Docket customDocket() {
	        return new Docket(DocumentationType.SWAGGER_2)
	                .apiInfo(apiInfo())      
	                .select()
	                .apis(RequestHandlerSelectors.any())
	                .paths(PathSelectors.any())
	                .build();
	    }

	    private ApiInfo apiInfo() {
	        Contact contact = new Contact("支付组", "", "");
	        return new ApiInfoBuilder()
	                .title("支付API接口")
	                .description("支付API接口")
	                .contact(contact)
	                .version("1.1.0")
	                .build();
	    }
}

注意：com.foriseland.fsoa.pay.controller 写自己的controller包路径。

三、在spring mvc配置xml里面加入Swagger配置

   <!-- swagger -->
   <bean class="com.foriseland.fsoa.pay.swagger.SwaggerConfig"></bean>
   <mvc:default-servlet-handler/>
   <mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"/>
   <mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/> 

注意：bean注入SwaggerConfig配置类

四、controller层的编写例子

类上面的注解
@Controller
@CrossOrigin
@Api(tags="账户信息控制类")
@RequestMapping("account")
public class AccountController{

    方法上面的注解
    @ApiOperation(value = "获取盈豆数量", notes = "获取盈豆数量", httpMethod = "POST")
    @RequestMapping(value="getBeansNumber", method=RequestMethod.POST)
    @ResponseBody
    public void getBeansNumber(@RequestBody BeansCountDto info, HttpServletResponse response) {

    }
}

五、启动项目

http://192.168.1.73:8080/fwas.pay.web.platform/swagger-ui.html

注意：这个我的ip、端口和项目名称，如果是自己的，就在访问地址最后加上swagger-ui.html在访问，到此就可以搞定测试了。