swagger2整合springmvc快速生成rest风格接口文档

Swagger可以用来快速生成RESTful API文档,使后台开发人员与移动端开发人员更好的对接.

Maven dependency
1
2
3
4
5
6
7
8
9
10
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.5.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.5.0</version>
</dependency>
配置Swagger
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2).forCodeGeneration(true).select().apis(RequestHandlerSelectors.any())
//过滤生成链接
.paths(PathSelectors.regex("/swagger/.*")).build().apiInfo(apiInfo());
}
//api接口作者相关信息
private ApiInfo apiInfo() {
Contact contact = new Contact("章国东", "http://zhangguodong.me", "zgdgude@gmail.com");
ApiInfo apiInfo = new ApiInfoBuilder().license("Apache License Version 2.0").title("xxx系统").description("接口文档").contact(contact).version("1.0").build();
return apiInfo;
}
}
在springmvc的xml文件中加入相关配置
1
2
3
4
5
6
 <!--<bean class="com.gude.config.SwaggerConfig" /> 使用bean申明可以去掉@configuration-->
<!--扫描@configuration注解-->
<context:component-scan base-package="com.gude.config"/>
<!--配置静态资源访问-->
<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"/>
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>
类接口添加相关说明
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
@Api(value = "HelloController", description = "Hello控制器")
@Controller
@RequestMapping("/swagger")
public class HelloController {
@GetMapping("/hello")
public ModelAndView helloWorld() {
ModelAndView mv = new ModelAndView();
mv.setViewName("hello");
return mv;
}

@ApiOperation("用户登录")
@ApiImplicitParams({@ApiImplicitParam(name = "username", value = "用户名", required = true, dataType = "string"), @ApiImplicitParam(name = "password", value = "密码", required = true, dataType = "string")})
@PostMapping("/login")
public ModelAndView login(String username, String password) {
ModelAndView mv = new ModelAndView();
mv.setViewName("success");
return mv;
}

@ApiOperation("json返回测试")
@ResponseBody
@GetMapping("/json")
public Person testJson() {
Person person = new Person("gude", "111111");
return person;
}
}
  • @ApiImplicitParam:对单个参数进行说明,其中dataType一定为小写
  • @Api:标志这个类为Swagger资源
  • @ApiOperation:描述了一种操作或通常针对特定的路径的HTTP方法。

更多注解可以查看官方说明

打开http://localhost:8080/project_name/swagger-ui.html ,project_name表示你启动项目的名称,如果你以根目录启动则没有project_name,当你看到如下界面就表示配置成功了

本次整合源码

参考官方文档