Spring boot swagger

swagger用于定义API文档。

好处：

• 前后端分离开发
• API文档非常明确
• 测试的时候不需要再使用URL输入浏览器的方式来访问Controller
• 传统的输入URL的测试方式对于post请求的传参比较麻烦（当然，可以使用postman这样的浏览器插件）
• spring-boot与swagger的集成简单

第一步：引入相关的jar包依赖

//swagger    compile('io.springfox:springfox-swagger2:2.7.0')    compile('io.springfox:springfox-swagger-ui:2.7.0')

第二步：在application类上加上@EnableSwagger2的注解开启swagger

第三步：UserController

package com.hj.controller;import com.hj.entity.Result;import com.hj.entity.User;import com.hj.repository.UserRepository;import com.hj.service.UserService;import com.hj.utils.ResultUtil;import io.swagger.annotations.*;import io.swagger.models.Response;import org.springframework.beans.factory.annotation.Autowired;import org.springframework.validation.BindingResult;import org.springframework.web.bind.annotation.*;import javax.validation.Valid;import java.util.List;/** * Created by huangjie on 2017/10/20. */@RestController@Api("userController相关api")public class UserController {    //如何实现在登录前进行统一判读用户是否登录过?不可以再Controller中的构造函数里面判断，因为Spring 程序已启动就把controller类实例化了    //在http请求的时候不会再实例化了。使用AOP就可以统一判断了    @Autowired    private UserRepository userRepository;    @Autowired    private UserService userService;    @GetMapping("/getlist")    public List<User> getUser(){        return userRepository.findAll();    }    @ApiOperation("添加用户")    @ApiImplicitParams({            //@ApiImplicitParam(paramType="header",name="name",dataType="String",required=true,value="用户的姓名",defaultValue="zhaojigang"),            @ApiImplicitParam(paramType="query",name="name",dataType="String",required=true,value="用户的姓名",defaultValue="zhaojigang"),            @ApiImplicitParam(paramType="query",name="pwd",dataType="String",required=true,value="用户的密码",defaultValue="wangna")    })    @GetMapping("add")    public User addUser(@RequestParam("name") String name,@RequestParam("pwd") String pwd){        User u=new User();        //u.setId(4);        u.setName(name);        u.setPwd(pwd);        return userRepository.save(u);    }    @ApiOperation("获取用户信息")    @ApiImplicitParams({                     @ApiImplicitParam(paramType="header",name="name",dataType="String",required=true,value="用户的姓名",defaultValue="zhaojigang"),          // @ApiImplicitParam(paramType="query",name="name",dataType="String",required=true,value="用户的姓名",defaultValue="zhaojigang"),                     @ApiImplicitParam(paramType="query",name="pwd",dataType="String",required=true,value="用户的密码",defaultValue="wangna")                 })     @ApiResponses({                     @ApiResponse(code=400,message="请求参数没填好"),                    @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")                 })    @RequestMapping(value="/getUser",method= RequestMethod.GET)     public User getUser(@RequestHeader("name") String name,@RequestParam("pwd") String pwd) {        System.out.println(name);        System.out.println(pwd);                 return userRepository.getUserByNameAndPwd(name,pwd);             }    @ApiOperation("添加用户")    @ApiImplicitParams({            @ApiImplicitParam(name="user",dataType="User",required=true,value="用户")    })    @PostMapping("add2")    public Result<User> addUser2(@Valid @RequestBody User user, BindingResult bindingResult, Response response){        if (bindingResult.hasErrors()){            //response.setHeaders("content-type","application/json;charset=UTF-8");           // return bindingResult.getFieldError().getDefaultMessage();           /* Result result=new Result();            result.setCode(1);            result.setMessage(bindingResult.getFieldError().getDefaultMessage());            return  result;*/           return ResultUtil.error(1,bindingResult.getFieldError().getDefaultMessage());        }        /*Result result=new Result();        result.setCode(0);        result.setMessage("成功");        result.setData(userRepository.save(user));        return result;*/        return ResultUtil.success(userRepository.save(user));    }    @ApiOperation("删除用户")    @ApiImplicitParams(            @ApiImplicitParam(paramType="query",name="id",dataType="Integer",required =true ,value = "用户id")    )    @RequestMapping(value="/delete",method=RequestMethod.GET)    public void deleteUser(@RequestParam("id") Integer id){        userRepository.delete(id);    }    @ApiOperation("查询用户")    @ApiImplicitParams(            @ApiImplicitParam(paramType="query",name="name",dataType="String",required =true ,value = "用户姓名")    )    @RequestMapping(value="/getuser",method=RequestMethod.GET)    public User getUser(@RequestParam("name") String name){        return userRepository.getUserByName(name);    }    @ApiOperation("根据ID查询用户")    @ApiImplicitParams(            @ApiImplicitParam(paramType="query",name="id",dataType="Integer",required =true ,value = "用户ID")    )    @RequestMapping(value="/getuserbyid",method=RequestMethod.GET)    public void getUserById(@RequestParam("id") Integer id) throws Exception{        userService.getUser(id);    }}

说明：

• @Api：用在类上，说明该类的作用
• @ApiOperation：用在方法上，说明方法的作用
• @ApiImplicitParams：用在方法上包含一组参数说明

• @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

• paramType：参数放在哪个地方

  header-->请求参数的获取：@RequestHeaderquery-->请求参数的获取：@RequestParampath（用于restful接口）-->请求参数的获取：@PathVariablebody（不常用）form（不常用）

  name：参数名
  dataType：参数类型
  required：参数是否必须传
  value：参数的意思
  defaultValue：参数的默认值

• @ApiResponses：用于表示一组响应

• @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

  code：数字，例如400
  message：信息，例如”请求参数没填好”
  response：抛出异常的类

• @ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用

• @ApiImplicitParam注解进行描述的时候）

• @ApiModelProperty：描述一个model的属性

以上这些就是最常用的几个注解了。

第五步：启动服务，浏览器输入”http://localhost:8080/swagger-ui.html”