JavaWeb项目中集成Swagger API文档

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#/中看到