在App后端开发中经常需要对移动客户端（Android、iOS）提供RESTful API接口，在后期版本快速迭代的过程中，修改接口实现的时候都必须同步修改接口文档，而文档与代码又处于两个不同的媒介，除非有严格的管理机制，不然很容易导致代码与接口文档不一致现象。

本文将介绍RESTful API的重磅好伙伴Swagger2，它可以轻松的整合到spring生态链中，并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量，同时又将说明内容整合入实现代码中，让维护文档和修改代码整合为一体，方便让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API.

通过观看创建项目及引入Mybatis，再执行以下操作

在pom.xml中引入依赖包

    			
     
      io.springfox
     			
     
      springfox-swagger2
     			
     
      2.6.1
     		
    		
    			
     
      io.springfox
     			
     
      springfox-swagger-ui
     			
     
      2.6.1
     		
    

编写Swagger2配置类

package org.morecare.config.swagger2;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.PathSelectors;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.service.ApiInfo;import springfox.documentation.service.Contact;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;/** * Swagger2配置类 * * @author lvgang * @create 2017-07-19 */@EnableSwagger2@Configurationpublic class Swagger2Config {    @Bean    public Docket createRestApi() {        return new Docket(DocumentationType.SWAGGER_2)                .apiInfo(apiInfo())                .select()                //为当前包路径                .apis(RequestHandlerSelectors.basePackage("org.morecare.test.controller"))                .paths(PathSelectors.any())                .build();    }    //构建 api文档的详细信息函数    private ApiInfo apiInfo() {        return new ApiInfoBuilder()                //页面标题                .title("Spring Boot 测试使用 Swagger2 构建RESTful API")                //创建人                .contact(new Contact("Lvgang", "http://www.aoreki-cn.com", "lvzg_abc@163.com"))                //版本号                .version("1.0")                //描述                .description("API 描述")                .build();    }}

通过@Configuration注解，让Spring来加载该类配置，@EnableSwagger2注解来启用Swagger2。

编写测试Controller            

package org.morecare.test.controller;import java.util.List;import org.morecare.config.handler.GlobalDefaultExceptionHandler;import org.morecare.test.bean.Demo;import org.morecare.test.service.DemoManageService;import org.slf4j.Logger;import org.slf4j.LoggerFactory;import org.springframework.beans.factory.annotation.Autowired;import org.springframework.web.bind.annotation.DeleteMapping;import org.springframework.web.bind.annotation.GetMapping;import org.springframework.web.bind.annotation.PathVariable;import org.springframework.web.bind.annotation.PostMapping;import org.springframework.web.bind.annotation.PutMapping;import org.springframework.web.bind.annotation.RequestMapping;import org.springframework.web.bind.annotation.RequestParam;import org.springframework.web.bind.annotation.RestController;import io.swagger.annotations.ApiImplicitParam;import io.swagger.annotations.ApiImplicitParams;import io.swagger.annotations.ApiOperation;/** * Demo管理控制层 *  * @author Administrator * */@RestController@RequestMapping("/demo")public class DemoManageController {		private final static Logger logger = LoggerFactory.getLogger(GlobalDefaultExceptionHandler.class);		@Autowired	private DemoManageService demoManageService;	    /**     * 查询列表     * @return     */	    @ApiOperation(value="DEMO查询", notes="根据DEMO名称查询")    @ApiImplicitParams({            @ApiImplicitParam(dataType = "java.lang.String", name = "name", value = "DEMO名称", required = true, paramType = "path")    })    @GetMapping(value = "/find/{name}")    public List
    
      getList(@PathVariable("name") String name){        logger.info("getList");        return demoManageService.getByName(name);    }    /**     * 按ID进行查询     * @param id     * @return     */    @ApiOperation(value="DEMO查询", notes="根据DEMO主键查询")    @GetMapping(value = "/findone/{id}")    public Demo get(@PathVariable("id") Integer id){        return demoManageService.getById(id);    }        /**     * 添加     * @param name     * @param age     * @return     */    @ApiOperation(value="创建DEMO", notes="根据传入的信息创建对象")    @PostMapping(value = "/")    public int add(@RequestParam("name") String name){    	Demo tt = new Demo();        tt.setName(name);        return demoManageService.add(name);    }    /**     * 更新     * @param id     * @param name     * @param age     * @return     */    @ApiOperation(value="DEMO更新", notes="根据主键更新DEMO数据")    @PutMapping(value = "/{id}")    public int update(@PathVariable("id") Integer id,@RequestParam("name") String name,@RequestParam("age") Integer age){    	Demo tt = new Demo();        tt.setName(name);        tt.setId(id);        return demoManageService.update(id, name);    }    /**     * 删除     * @param id     */    @ApiOperation(value="DEMO删除", notes="根据主键删除DEMO数据")    @DeleteMapping(value = "/{id}")    public void del(@PathVariable("id") Integer id){    	demoManageService.remove(id);    }	}
    

    Swagger 注解介绍：

• 通过@ApiOperation注解来给API增加说明
• 通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明
• 通过@ApiIgnore来忽略那些不想让生成RESTful API文档的接口

启动查看

完成以上工作，通过Main启动项目后访问  打开以下页面表示配置成功！

通过输入参数，并眯击Try it out！就可以进行测试了