Spring-Boot 整合Swagger2（在线生成接口文档）

Swagger是一款在线的接口生成和在线功能测试的工具

Swagger 是一个规范和完整的在线接口生成框架，用于生成、描述、调用和在线可视化 Restful 接口风格的 Web 服务。是使客户端和后端系统作为服务器以同样更新速度来实时更新接口。后端文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger具有部署集成简单和功能强大的API的特点。

　　官网：http://swagger.io/

　　GitHub地址：https://github.com/swagger-api/swagger-ui

1.Maven 依赖

<!-- 配置Swagger 生成API文档 -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.6.1</version>
</dependency>

<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.6.1</version>
</dependency>
<!-- ============================== -->

2.配置Swagger的配置类

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author gaojme
 * @ClassName Swagger2
 * 类描述: Swagger配置类
 * 其实这个配置类，只要了解具体能配置哪些东西就好了，毕竟这个东西配置一次之后就不用再动了。
 *      特别要注意的是里面配置了api文件也就是controller包的路径，不然生成的文档扫描不到接口。
 * @create 2018-06-12 18:02
 * 备注:写这段代码的时候，只有上帝和我知道它是干嘛的。现在,只有上帝知道。
 **/
@Configuration  //用configuration 注解该类等价于再xml文件中配置了beans；
                // 用@Bean标注方法等价于XML中配置bean
                // Application.class(启动类) 加上注解@EnableSwagger2 表示开启Swagger
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.szsm.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }
    
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档") //大标题
                .description("简单优雅的restfun风格，http://blog.csdn.net/testspringboot")//描述
                .version("1.0")
                .termsOfServiceUrl("No terms of service")
                .contact("nice")//作者(已过时)
                .license("The Apace Licese, Version 2.0") //链接显示文字
                .licenseUrl("http://www.baidu.com")//网站连接
                .build();
    }
    
}

注：用@Configuration注解类的结果，等价于XML中配置beans；用@Bean标注方法等价于XML中配置bean。

3.启动类的配置()

@SpringBootApplication
// @Mapper 这里可以使用@Mapper注解，但是每个mapper都加注解比较麻烦，所以统一配置@MapperScan在扫描路径在application类中
@MapperScan("cn.szsm.mapper")
@EnableSwagger2    //表示开启Swagger(如果使用Swagger2 需要加这句话) 
public class TestSpringbootApplication {

   public static void main(String[] args) {
      SpringApplication.run(TestSpringbootApplication.class, args);
   }


   /**
    * SpringBoot使用FastJson
    * 描述：阿里巴巴FastJson是一个Json处理工具包，包括“序列化”和“反序列化”两部分，它具备如下特征：
         速度最快，测试表明，fastjson具有极快的性能，超越任其他的Java Json parser。包括自称最快的JackJson；
         功能强大，完全支持Java Bean、集合、Map、日期、Enum，支持范型，支持自省；无依赖，能够直接运行在Java SE 5.0以上版本；
         支持Android；开源 (Apache 2.0) 另外一点，SpringBoot默认json转换器为Jackson
    * @return
    */
   @Bean
   public HttpMessageConverters fastJsonHttpMessageConverters()
   {
      //创建FastJson信息转化对象
      FastJsonHttpMessageConverter fastJsonHttpMessageConverter = new FastJsonHttpMessageConverter();
      //创建Fastjson 对象并设定序列化规则
      FastJsonConfig fastJsonConfig = new FastJsonConfig();
      fastJsonConfig.setSerializerFeatures(SerializerFeature.PrettyFormat);
      // 中文乱码解决方案
      List<MediaType> mediaTypes = new ArrayList<>();
      mediaTypes.add(MediaType.APPLICATION_JSON_UTF8);
      fastJsonHttpMessageConverter.setSupportedMediaTypes(mediaTypes);

      //规则赋予转化对象
      fastJsonHttpMessageConverter.setFastJsonConfig(fastJsonConfig);
      return new HttpMessageConverters(fastJsonHttpMessageConverter);
   }




}

4.controller的配置

@RestController
public class UserController {

    private  static Logger logger = LoggerFactory.getLogger(UserController.class);

    @Autowired
    private UserService userService;
    /**
     * 根据ID查询用户
     * @param id
     * @return
     */
    @ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
    @RequestMapping(value = "user/{id}", method = RequestMethod.GET)
    public ResponseEntity<JsonResult> getUserById (@PathVariable(value = "id") Integer id){
        JsonResult r = new JsonResult();
        try {
            User user = userService.getUserById(id);
            r.setResult(user);
            r.setStatus("ok");
            logger.info("运行成功！");
        } catch (Exception e) {
            logger.error(e.getMessage());
            r.setResult(e.getClass().getName() + ":" + e.getMessage());
            r.setStatus("error");
            e.printStackTrace();
        }
        return ResponseEntity.ok(r);
    }

    /**
     * 查询用户列表
     * @return
     */
    @ApiOperation(value="获取用户列表", notes="获取用户列表")
    @RequestMapping(value = "users", method = RequestMethod.GET)
    public ResponseEntity<JsonResult> getUserList (){
        JsonResult r = new JsonResult();
        try {
            List<User> userList = new ArrayList<User>(userService.getUserList());
            r.setResult(userList);
            r.setStatus("ok");
        } catch (Exception e) {
            r.setResult(e.getClass().getName() + ":" + e.getMessage());
            r.setStatus("error");
            e.printStackTrace();
        }
        return ResponseEntity.ok(r);
    }

    /**
     * 添加用户
     * @param user
     * @return
     */
    @ApiOperation(value="创建用户", notes="根据User对象创建用户")
    @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
    @RequestMapping(value = "user", method = RequestMethod.POST)
    public ResponseEntity<JsonResult> add (@RequestBody User user){
        JsonResult r = new JsonResult();
        try {
            userService.add(user);
            r.setResult(user.getId());
            r.setStatus("ok");
        } catch (Exception e) {
            r.setResult(e.getClass().getName() + ":" + e.getMessage());
            r.setStatus("error");
            e.printStackTrace();
        }
        return ResponseEntity.ok(r);
    }

    /**
     * 根据id删除用户
     * @param id
     * @return
     */
    @ApiOperation(value="删除用户", notes="根据url的id来指定删除用户")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path")
    @RequestMapping(value = "user/{id}", method = RequestMethod.DELETE)
    public ResponseEntity<JsonResult> delete (@PathVariable(value = "id") Integer id){
        JsonResult r = new JsonResult();
        try {
            userService.delete(id);
            r.setResult(id);
            r.setStatus("ok");
        } catch (Exception e) {
            r.setResult(e.getClass().getName() + ":" + e.getMessage());
            r.setStatus("error");

            e.printStackTrace();
        }
        return ResponseEntity.ok(r);
    }

    /**
     * 根据id修改用户信息
     * @param user
     * @return
     */
    @ApiOperation(value="更新信息", notes="根据url的id来指定更新用户信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long",paramType = "path"),
            @ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "User")
    })
    @RequestMapping(value = "user/{id}", method = RequestMethod.PUT)
    public ResponseEntity<JsonResult> update (@PathVariable("id") Integer id, @RequestBody User user){
        JsonResult r = new JsonResult();
        try {
            User u = userService.getUserById(id);
            u.setUsername(user.getUsername());
            u.setAge(user.getAge());
            userService.update(id, u);
            r.setResult(u);
            r.setStatus("ok");
        } catch (Exception e) {
            r.setResult(e.getClass().getName() + ":" + e.getMessage());
            r.setStatus("error");

            e.printStackTrace();
        }
        return ResponseEntity.ok(r);
    }

    @ApiIgnore//使用该注解忽略这个API
    @RequestMapping(value = "/hi", method = RequestMethod.GET)
    public String  jsonTest() {
        return " hi you!";
    }
}

5.application.yml的配置文件(可配置，也可默认)

这里添加/springboot 是为了直接在地址栏中输入 http://localhost:8080/springboot/swagger-ui.html 方便测试

参考自：https://blog.csdn.net/column/details/16272.html(写的很好,但是自己技术有限，很多整合文章还没有测试成功！)