07-2-接口文档管理工具-swagger注解使用__ev

2026/10/3 3:42:27 拓冰建站浏览量

swagger参考demo

package com.example.swagger2.controller;import com.example.swagger2.exception.SwaggerException;
import com.example.swagger2.model.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;import java.util.HashMap;
import java.util.Map;@Api(tags = "接口服务", value = "/api/v1/swagger/**")
@RestController
@RequestMapping("/api/v1/swagger")
public class ApiController {@ApiOperation("保存用户信息")@ApiImplicitParams({@ApiImplicitParam(name = "name", value = "名字", required = true, paramType = "path"),@ApiImplicitParam(name = "age", dataType = "int", value = "年龄", required = true, paramType = "query")})@PostMapping("/{name}")@ResponseBodypublic Boolean save(@PathVariable("name") String name,@RequestParam("age") Integer age) {userInfo.put(name, new User(name, age));return true;}@ApiOperation("查询年龄")@ApiImplicitParams({@ApiImplicitParam(name = "name", value = "名字", required = true, paramType = "path")})@ApiResponses({@ApiResponse(code = 404, message = "用户不存在", response = SwaggerException.class)})@GetMapping("/{name}")@ResponseBodypublic User get(@PathVariable("name") String name) throws SwaggerException {if (!userInfo.containsKey(name)) {throw new SwaggerException(name + "不存在！");}return userInfo.get(name);}public static Map<String, User> userInfo = new HashMap<>(16);
}

package com.example.swagger2.model;import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;@Data
@AllArgsConstructor
@ApiModel(description = "用户信息")
public class User {@ApiModelProperty(value = "姓名")String name;@ApiModelProperty(value = "年龄")Integer age;
}

swagger相关注解介绍

注解	位置	说明
@Api	类	加载Controller类上,表示对类的说明
@ApiModel	类(通常是实体类)	描述实体类的作用，通常表示接口接收参数的实体对象
@ApiModelProperty	属性	描述实体类的属性，（用对象接收参数时，描述对象的一个字段）
@ApiOperation	方法	说明方法的用途、作用
@ApiImplicitParams	方法	表示一组参数说明
@ApiImplicitParam	方法	用在@ApiImplicitParams注解中，指定一个请求参数的各个方面的属性
@ApiParam	方法入参或者方法之上	单个参数的描述信息，描述form表单、url参数

@ApiImplicitParam注解详解：

属性	取值	作用
paramType		查询参数类型
	path	以地址的形式（rest风格）提交数据
	query	直接跟参数完成自动映射赋值(/add/user?name=zhangsan)
	body	以流的形式提交仅支持POST
	header	参数在request headers 里边提交
	form	以form表单的形式提交仅支持POST
dataType		参数的数据类型只作为标志说明，并没有实际验证
	Long
	String
name		接收参数名(方法入参的名称)
value		接收参数的意义描述（描述信息）
required		参数是否必填
	true	必填
	false	非必填
defaultValue		默认值

其它注解：

@ApiResponse：HTTP响应其中1个描述

@ApiResponses：HTTP响应整体描述

@ApiIgnore：使用该注解忽略这个API

@ApiError ：发生错误返回的信息

把注解应用到项目中

package com.itheima.stock.controller;import com.itheima.stock.pojo.entity.SysUser;
import com.itheima.stock.service.UserService;
import com.itheima.stock.vo.req.LoginReqVo;
import com.itheima.stock.vo.resp.LoginRespVo;
import com.itheima.stock.vo.resp.R;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;import java.util.Map;
@Api(tags = "用户相关接口处理器")
@RestController
@RequestMapping("/api")
public class UserController {@Autowiredprivate UserService userService;
@ApiOperation(value = "根据用户名查询用户信息")
@ApiImplicitParam(name = "username", value = "用户名", required = true, paramType = "path")@GetMapping("/user/{username}")public SysUser findUserInfoByUsername(@PathVariable("username") String username) {return userService.findUserInfoByUsername(username);}
@ApiOperation(value = "用户登录")@PostMapping("/login")public R<R<LoginRespVo>> login(@RequestBody LoginReqVo loginReqVo) {return R.ok(userService.login(loginReqVo));}@ApiOperation(value = "获取验证码")@GetMapping("/captcha")public R<Map> getCaptchaCode() {return userService.getCaptchaCode();}
}

查看效果

建站实战干货

07-2-接口文档管理工具-swagger注解使用__ev