Spring boot swagger_io.swagger.models.responses-CSDN博客

本文介绍如何将Swagger集成到Spring Boot项目中，以实现RESTful API的文档化与测试。通过简单的步骤，包括添加依赖、配置注解等，即可快速启用Swagger，并通过浏览器访问API文档。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

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-->请求参数的获取：@RequestHeader
query-->请求参数的获取：@RequestParam
path（用于restful接口）-->请求参数的获取：@PathVariable
body（不常用）
form（不常用）

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

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

code：数字，例如400
message：信息，例如”请求参数没填好”
response：抛出异常的类
@ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用
@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：描述一个model的属性