SpringBoot + Swagger2 自动生成API接口文档

spring-boot作为当前最为流行的Java web开发脚手架，相信越来越多的开发者会使用其来构建企业级的RESTFul API接口。这些接口不但会服务于传统的web端（b/s），也会服务于移动端。在实际开发过程中，这些接口还要提供给开发测试进行相关的白盒测试，那么势必存在如何在多人协作*享和及时更新API开发接口文档的问题。
假如你已经对传统的wiki文档共享方式所带来的弊端深恶痛绝，那么尝试一下Swagger2 方式，一定会让你有不一样的开发体验：

功能丰富：支持多种注解，自动生成接口文档界面，支持在界面测试API接口功能；
及时更新：开发过程中花一点写注释的时间，就可以及时的更新API文档，省心省力；
整合简单：通过添加pom依赖和简单配置，内嵌于应用中就可同时发布API接口文档界面，不需要部署独立服务。

1、添加pom依赖

需要添加的依赖为swagger2核心包和swagger-ui界面包，笔者写文章时的最新版本为2.7.0，实际引用可以去maven官网查询最新可使用版本。

代码块

<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>

2、将swagger-ui中的界面配置至spring-boot环境

spring-boot有自己的一套web端拦截机制，若需要看到swagger发布的api文档界面，需要做一些特殊的配置，将springfox-swagger-ui包中的ui界面暴露给spring-boot资源环境。

代码块

@Configuration

public class WebMvcConfig extends WebMvcConfigurerAdapter {

    @Override

    public void addResourceHandlers(ResourceHandlerRegistry registry) {

        registry.addResourceHandler("/js/**").addResourceLocations("classpath:/js/");

        registry.addResourceHandler("swagger-ui.html")

                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")

                .addResourceLocations("classpath:/META-INF/resources/webjars/");

    }

}

3、配置API文档页基本信息

spring-boot 和 swagger 整合时，可以通过注解注入相关配置。通过这些配置可以指定在spring-boot启动时扫描哪些controller层的文件夹，另外可以指定API文档页的标题和描述信息等内容。

代码块

@Configuration

@EnableSwagger2

public class Swagger2 {

    @Bean

    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)

                .apiInfo(apiInfo())

                .select()

                .apis(RequestHandlerSelectors.basePackage("com.xx.web.controller"))

                .paths(PathSelectors.any())

                .build();

    }

    private ApiInfo apiInfo() {

        return new ApiInfoBuilder()

                .title("xx项目 RESTful APIs")

                .description("xx项目后台api接口文档")

                .version("1.0")

                .build();

    }

}

4、API文档编写示例

我们一般在Controller层，将详尽的API接口输入输出在代码中通过注解进行相关描述，下面给出一个接口描写示例，具体的写法可以参考其api文档的具体说明：

代码块

@Api(value = "PageController", description = "用户登录登出接口")

@Controller

@RequestMapping("/")

public class PageController {

    @ApiOperation(value="用户登录", notes="用户登录接口")

    @ApiImplicitParams({

          @ApiImplicitParam(name = "username", value = "用户名", required = true ,dataType = "string"),

          @ApiImplicitParam(name = "passwd", value = "密码", required = true ,dataType = "string")

    })

    @RequestMapping(value = "/login",method = {RequestMethod.POST,RequestMethod.GET})

    @ResponseBody

    public ModelMap login(Users data, HttpServletRequest request){

       xxx...

    }

}

5、在线查看及测试API文档

完成API文档的编写工作之后，正常启动spring-boot，假如后台端口为8080，那么访问http://127.0.0.1:8080/swagger-ui.html，可以访问到如下界面：

通过该界面，不仅可以看到自动生成的所有API文档信息，还可以对任意接口进行在线测试，非常方便：

秒客网