Spring Boot : Swagger 2

　　每次修改完代码需要找原本的API时楼主的内心是痛苦的，因为一般情况下都找不到，需要重新写一份。如果使用Swagger的话，只要加几个注解就可以实时生成最新的在线API文档，而且不仅仅是文档，同时支持API接口的测试。下面呢，给大家分享一下Spring Boot 集成 Swagger 的步骤。

一、引入jar包

 　　　　　<!-- Swagger2核心包-->
         <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
         <dependency>
             <groupId>io.springfox</groupId>
             <artifactId>springfox-swagger2</artifactId>
             <version>2.7.0</version>
         </dependency>

         <!-- Swagger2 UI包，前端展示API文档 -->
         <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
         <dependency>
             <groupId>io.springfox</groupId>
             <artifactId>springfox-swagger-ui</artifactId>
             <version>2.7.0</version>
         </dependency>

二、配置SwaggerConfig

 package com.bjgoodwill.oip.major.config;

 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;

 /**
  * @Description： swagger配置文件
  * @Date 2018/7/13 10:50
  * @Author HQueen
  */
 @Configuration
 @EnableSwagger2
 public class SwaggerConfig {
     @Bean
     public Docket api() {
         return new Docket(DocumentationType.SWAGGER_2)
                 .apiInfo(apiInfo())
                 .select()
                 .apis(RequestHandlerSelectors.basePackage("com.queeen.major"))
                 .paths(PathSelectors.any())
                 .build();
     }

     private ApiInfo apiInfo() {
         return new ApiInfoBuilder()
                 .title("API文档")
                 .build();
     }
 }

其中，@EnableSwagger2注解来启用Swagger2，apis()定义了扫描的包路径

三、编写接口

Spring Boot中包含了一些注解，对应于HTTP协议中的方法：

@GetMapping对应HTTP中的GET方法；

@PostMapping对应HTTP中的POST方法；

@PutMapping对应HTTP中的PUT方法；

@DeleteMapping对应HTTP中的DELETE方法；

@PatchMapping对应HTTP中的PATCH方法。

 package com.bjgoodwill.oip.major.system.controller;

 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.stereotype.Controller;
 import org.springframework.ui.Model;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.ResponseBody;

 import com.bjgoodwill.oip.core.enums.ExceptionEnum;
 import com.bjgoodwill.oip.core.exception.CoreException;
 import com.bjgoodwill.oip.core.util.StringUtils;
 import com.bjgoodwill.oip.major.system.model.UserModel;
 import com.bjgoodwill.oip.major.system.service.UserService;
 import com.bjgoodwill.oip.major.system.util.R;

 import io.swagger.annotations.Api;
 import io.swagger.annotations.ApiOperation;
 import io.swagger.annotations.ApiParam;

 /**
  * @Date 2018/7/13 10:50
  * @Author HQueen
  */
 @Controller
 @RequestMapping(value="/user")
 @Api(tags="用户信息")
 public class UserController {

     @Autowired
     UserService userService;

     /** 验证用户信息
      * @param account
      * @return
      */
     @ApiOperation(value="验证用户信息", notes="验证用户信息")
     @PostMapping(value="/verify")
     @ResponseBody
     public UserModel verifyUser(@ApiParam(name="account", value="用户名") String account){

         if (StringUtils.isEmpty(account)) {
             throw new CoreException(ExceptionEnum.REQUEST_NULL);
         }

         UserModel model = userService.findByAccount(account);

         return model;
     }

     /** 跳转至用户修护界面
      * @param id
      * @param model
      * @return
      */
     @ApiOperation(value="跳转至用户修护界面", notes="跳转至用户修护界面")
     @GetMapping(value="/pre/{id}")
     public String preUpdate(@ApiParam(name="id", value="用户ID") Long id, Model model) {

         UserModel userModel = userService.getByPrimaryKey(id);

         model.addAttribute("model", userModel);

         return "edit";
     }

     /** 修改用户基本信息
      * @param userModel
      * @return
      */
     @ApiOperation(value="修改用户基本信息", notes="修改用户基本信息")
     @PostMapping(value="/update")
     @ResponseBody
     public R update(@ApiParam(name="userModel", value="用户信息类") UserModel userModel) {

         if (userService.update(userModel) > 0) {
             return R.ok();
         }

         return R.error();
     }
 }

四、启动及测试

　　如上图所示，点击 Try it out! 就可以进行在线测试。

PS：

1. swagger和swagger 2的区别

　　在官方文档上是这么说明的：

What is the relationship between swagger-ui and springfox-swagger-ui?

• Swagger Spec is a specification.

• Swagger Api - an implementation of that specification that supports jax-rs, restlet, jersey etc.

• Springfox libraries in general - another implementation of the specification focused on the spring based ecosystem.

• Swagger.js and Swagger-ui - are client libraries in javascript that can consume swagger specification.

• springfox-swagger-ui - the one that you’re referring to, is just packaging swagger-ui in a convenient way so that spring services can serve it up.

　　总的来说就是：

　　　　1. Swagger 是一种规范。

　　　　2. springfox-swagger 是基于 Spring 生态系统的该规范的实现。

　　　　3. springfox-swagger-ui 是对 swagger-ui 的封装，使得其可以使用 Spring 的服务

2. 其他注解方式

　　在上述 demo 中，楼主使用@ApiParam注解对参数进行描述，下面呢，楼主提供第二种注解方式。

 package com.bjgoodwill.oip.major.system.controller;

 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.stereotype.Controller;
 import org.springframework.ui.Model;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestBody;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.ResponseBody;

 import com.bjgoodwill.oip.core.enums.ExceptionEnum;
 import com.bjgoodwill.oip.core.exception.CoreException;
 import com.bjgoodwill.oip.core.util.StringUtils;
 import com.bjgoodwill.oip.major.system.model.UserModel;
 import com.bjgoodwill.oip.major.system.service.UserService;
 import com.bjgoodwill.oip.major.system.util.R;

 import io.swagger.annotations.Api;
 import io.swagger.annotations.ApiImplicitParam;
 import io.swagger.annotations.ApiImplicitParams;
 import io.swagger.annotations.ApiOperation;
 import io.swagger.annotations.ApiParam;

 /**
  * @Date 2018/7/13 10:50
  * @Author HQueen
  */
 @Controller
 @RequestMapping(value="/user")
 @Api(tags="用户信息")
 public class UserController {

     @Autowired
     UserService userService;

     /** 验证用户信息
      * @param account
      * @return
      */
     @ApiOperation(value="验证用户信息", notes="验证用户信息")
     @PostMapping(value="/verify")
     @ApiImplicitParams({
         @ApiImplicitParam(name="account", value="用户名", required=true, paramType="query", dataType="String")
     })
     @ResponseBody
     public UserModel verifyUser(String account){

         if (StringUtils.isEmpty(account)) {
             throw new CoreException(ExceptionEnum.REQUEST_NULL);
         }

         UserModel model = userService.findByAccount(account);

         return model;
     }

     /** 跳转至用户修护界面
      * @param id
      * @param model
      * @return
      */
     @ApiOperation(value="跳转至用户修护界面", notes="跳转至用户修护界面")
     @GetMapping(value="/pre/{id}")
     @ApiImplicitParams({
         @ApiImplicitParam(name="id", value="用户ID", required=true, paramType="path", dataType="Long")
     })
     public String preUpdate(Long id, Model model) {

         UserModel userModel = userService.getByPrimaryKey(id);

         model.addAttribute("model", userModel);

         return "edit";
     }

     /** 修改用户基本信息
      * @param userModel
      * @return
      */
     @ApiOperation(value="修改用户基本信息", notes="修改用户基本信息")
     @PostMapping(value="/update")
     @ResponseBody
     public R update(@RequestBody @ApiParam(name="userModel", value="用户信息类") UserModel userModel) {

         if (userService.update(userModel) > 0) {
             return R.ok();
         }

         return R.error();
     }
 }