0 本文主要涉及
在基于Spring和SpringMVC的前后端分离的JavaWeb项目中生成Swagger API文档(使用SpringFox来实现)。
1 SpringFox和Swagger简介
结合SpringFox通过注解的形式自动生成Swagger API文档(HTML页面形式),该文档还具有简单的接口调试功能。
官网:http://springfox.github.io/springfox/
2 SpringFox配置集成
0 依赖配置
<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>
1 SpringBean配置
通过JavaConfig形式
@Configuration
@EnableWebMvc
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket myDocket() {
Docket docket = new Docket(DocumentationType.SWAGGER_2);
ApiInfo apiInfo = new ApiInfoBuilder()
.title("API接口文档")
.description("")
.contact(new Contact("", "", ""))
.version("1.0")
.build();
docket.apiInfo(apiInfo);
//设置只生成被Api这个注解注解过的Ctrl类中有ApiOperation注解的api接口的文档
docket.select().apis(RequestHandlerSelectors.withClassAnnotation(Api.class)).apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).build();
return docket;
}
}
在SpringMVC的Bean中写入资源路径映射
<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"/>
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>
如果项目使用了Shiro控制页面访问权限需要在过滤器中加入以下配置,方便文档使用
<!--swagger接口文档-->
/swagger*/**=anon
/v2/**=anon
/webjars/**=anon
3 Swagger使用示例
@RestController
@RequestMapping("/user")
@Api(tags = "UserinfoCtrl", description = "用户信息相关")
public class UserInfoCtrl
{
@Autowired
private UserInfoService userInfoService;
@RequestMapping("/getInfo")
@ApiOperation(value = "获取用户信息", httpMethod = "GET", notes = "显示用户信息,不显示密码")
public Object getInfo() throws MyMessageException
{
return userInfoService.getInfo();
}
@RequestMapping("/login")
@ApiOperation(value = "登录", httpMethod = "POST", notes = "说明。。。")
@ApiImplicitParams({
@ApiImplicitParam(name = "name", value = "用户名", required = true, paramType = "query", dataType = "String"),
@ApiImplicitParam(name = "password", value = "密码(MD5)", required = true, paramType = "query", dataType = "String"),
@ApiImplicitParam(name = "rememberMe", value = "是否记住登录状态", defaultValue = "false", paramType = "query", dataType = "boolean"),})
public Object login(@Valid LoginVO user, @RequestParam(defaultValue = "false") Boolean rememberMe, HttpServletRequest request) throws Exception
{
//。。。
}
}
生成的文档可在http://host地址:端口/项目名/swagger-ui.html#/中看到