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,当你看到如下界面就表示配置成功了

本次整合源码

参考官方文档