SpringBoot&Swagger构建REST API并生成API文档

背景：
现在的网站架构基本都由原来的后端渲染，
变成了：前端渲染、先后端分离的形态.

前后端交互的方式：api接口
api文档是提升开发效率

swagger就是一款让你更好的书写API文档的框架。

没有swagger之前文档都是手写api,有写在confluence上，也有在readme里的。文档书写工具加多，而swagger有更好的支持。

同类产品轻量级的rap 开发者阿里巴巴github地址
swagger生态使用图

红颜色的是swaggger官网方推荐的。
swagger-ui

这玩意儿从名字就能看出来，用来显示API文档的。和rap不同的是，它不可以编辑。

点进去

swagger-editor

就是一个在线编辑文档说明文件（swagger.json或swagger.yaml文件）的工具，以方便生态中的其他小工具（swagger-ui）等使用。
左边编辑，右边立马就显示出编辑内容来。

编辑swagger说明文件使用的是yaml语法具体的内容可以去官网查看。

各种语言版本的根据annotation或者注释生成swagger说明文档的工具

目前最流行的做法，就是在代码注释中写上swagger相关的注释，然后，利用小工具生成swagger.json或者swagger.yaml文件。

swagger-validator

这个小工具是用来校验生成的文档说明文件是否符合语法规定的。用法非常简单，只需url地址栏，根路径下加上一个参数url，参数内容是放swagger说明文件的地址。即可校验。

docker hub地址为：https://hub.docker.com/r/swaggerapi/swagger-validator/

swagger-codegen

代码生成器，脚手架。可以根据swagger.json或者swagger.yml文件生成指定的计算机语言指定框架的代码。

mock server

这个目前还没有找到很合适的mock工具，包括rap也好，其他API文档工具也好，都做的不够完善，大多就是根据说明文件，例如swagger.json等生成一些死的静态的mock数据，不能够根据限定条件：例如“只能是数字，必传”等做出合理的回应。

然后与SpringBoot整合
相信越来越多的开发者会使用其来构建企业级的RESTFul API接口。
这些接口不但会服务于传统的web端（b/s），也会服务于移动端。在实际开发过程中，这些接口还要提供给开发测试进行相关的白盒测试，那么势必存在如何在多人协作中共享和及时更新API开发接口文档的问题。

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

第一步添加pom依赖
需要添加的依赖为swagger2核心包和swagger-ui界面包
这里使用2.7.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>

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，可以访问到如下界面：

https://img-blog.csdn.net/20170806154827966?watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQvYW1vbjE5OTE=/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/gravity/SouthEast

https://img-blog.csdn.net/20170806154904366?watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQvYW1vbjE5OTE=/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/gravity/SouthEast