SpringMVC中使用swagger2

swagger，一个API文档生成工具，当编写商业项目时，每个项目之间可能需要调用其他项目的API接口，比如说前后端分离项目，这种时候需要写API文档，文档，程序员最讨厌自己写以及别人不写的一个东西，而Swagger就可以根据在项目中配置的注解自动生成文档，那么接下来就开始添加这个小东西

引入jar包

 <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配置类

@EnableWebMvc
@EnableSwagger2
@Configuration
public class SwaggerConfig extends WebMvcConfigurationSupport {

	/**
	 * 通过createRestApi函数创建Docket的Bean之后，
	 * apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）
	 * select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，
	 * apis()函数扫描所有Controller中定义的API， 并产生文档内容（除了被@ApiIgnore指定的请求）
	 * @return
	 */
	@Bean
	public Docket createRestApi() {

		return new Docket(DocumentationType.SWAGGER_2)
//				.globalOperationParameters(operationParameters)
				.apiInfo(apiInfo())
				.select()
				.apis(RequestHandlerSelectors.any())
				.paths(PathSelectors.any())
				.build();
		
	}

	/**
	 * 创建该Api的基本信息（这些基本信息会展现在文档页面中）
	 * @return
	 */
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				.title("标题")
				.termsOfServiceUrl("http://www.itrip.com/auth")
				.contact("[email protected]")
				.version("1.0")
				.build();
	}
}

注意在springMVC配置文件中添加

<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/" />

避免被拦截掉

使用

使用注解在controller类上声明
@Api(tags = “所在类”) =》 声明类
@ApiOperation(value = “接口名”,notes = “接口描述”,httpMethod = “发送方式”) = 》 声明接口
@ApiParam(value = “参数名称”,name = “参数名”) =》 声明参数

示例：

@Controller
@Api(tags = "UserController")
public class UserInfoController {

    @Autowired
    private UserInfoService userInfoService;

    @ApiOperation(value = "接口名",notes = "接口描述",httpMethod = "post")
    @RequestMapping(value="login",method= RequestMethod.POST)
    @ResponseBody
    public Dto login(
			@RequestParam("userCode")
			@ApiParam(value = "参数说明",name = "参数名") String userCode){

        ItripUser user = userInfoService.getUserInfo(userCode);

        return DtoUtil.returnDataSuccess(user);
    }
}

注意在声明方法的时候最好指明接口访问当时访问方式，就是@RequestMapping中method属性，否则swagger文档中会把所有请求方式的方法显示，现的特别杂乱，还有@RequestParam最好也加上，否则swagger上的测试功能可能无法使用

全部做完后重启项目，访问：** 项目地址/swagger-ui.html**就好了

常见异常：访问页面报404

1、检查是否配置springMVC静态资源

2、检查路径是否正确