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();

     }

 }