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("yao.liu2015@bdqn.cn")
.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、检查路径是否正确