写点什么

API 文档构建工具 - Swagger2 简单应用

  • 2022 年 4 月 29 日
  • 本文字数:2062 字

    阅读完需:约 7 分钟

return new ApiInfoBuilder()


.title( "用户管理接口 API 文档" )


.version( "1.0" )


.build();


}


}


@Api 作用到类上面 说明类的作用


@Api(tags=“APP 用户注册 Controller”)


@ApiModel


用于响应类上,表示一个返回响应数据的信息


(这种一般用在 post 创建的时候,使用 @RequestBody 这样的场景,


请求参数无法使用 @ApiImplicitParam 注解进行描述的时候)


@ApiModelProperty:用在属性上,描述响应类的属性


@ApiOperation


@ApiOperation:“用在请求的方法上,说明方法的作用”


value=“说明方法的作用”


notes="方法的备注说明


@ApiOperation(value=“用户注册”,notes=“手机号、密码都是必填项,年龄是选填项,但必须是数字”)


@ApiImplicitParams:用在请求的方法上,包含一组参数说明


@ApiImplicitParam:用在 @ApiImplicitParams 注解中,指定一个请求参数的配置信息


name:参数名


value:参数的汉字说明、解释


required:参数是否必须传


paramType:参数放在哪个地方


· header --> 请求参数的获取:@RequestHeader


· query --> 请求参数的获取:@RequestParam


· path(用于 restful 接口)–> 请求参数的获取:@PathVariable


· body(不常用)


· form(不常用)


dataType:参数类型,默认 String,其它值 dataType=“Integer”


defaultValue:参数的默认值


@ApiImplicitParams({


@ApiImplicitParam(name=“mobile”,value=“手机


号”,required=true,paramType=“form”),


@ApiImplicitParam(name=“password”,value=“密


码”,required=true,paramType=“form”),


@ApiImplicitParam(name=“age”,value=“年


龄”,required=true,paramType=“form”,dataType=“Integer”)


})


@ApiResponses


@ApiResponses:用于请求的方法上,表示一组响应


@ApiResponse:用在 @ApiResponses 中,一般用于表达一个错误的响应信息


code:数字,例如 400


message:信息,例如"请求参数没填好"


response:抛出异常的类


@ApiOperation(value = “select 请求”, notes = “多个参数,多种的查询参数类型”)


@ApiResponses({


@ApiResponse(code=400, message=“请求参数没填好”),


@ApiResponse(code=404, message=“请求路径没有或页面跳转路径不对”)


})


@ApiModel


@ApiModel:用于响应类上,表示一个返回响应数据的信息


(这种一般用在 post 创建的时候,使用 @RequestBody 这样的场景,


请求参数无法使用 @ApiImplicitParam 注解进行描述的时候)


@ApiModelProperty:用在属性上,描述响应类的属性


@ApiModel(description= “返回响应数据”)


public class RestMessage implements Serializable{


@ApiModelProperty(value = “是否成功”)


private boolean success=true;


@ApiModelProperty(value = “返回对象”)


private Object data;


@ApiModelProperty(value = “错误编号”)


private Integer errCode;


@ApiModelProperty(value = “错误信息”)


private String message;


/* getter/setter */


}


用法展示






其他情况类似


//RestController==controller+responseBody


@Api(tags = "APP 用户注册 Controller")


@RestController


public class UserController {


@Autowired


private UserService userService;


@ApiOperation(value = "根据用户 id 查询用户记录")


@ApiImplicitParam(name = "userId", value = "查询参数", required = true, paramType = "path")


@GetMapping("one/{id}")


public User sayUser(@PathVariable Integer id) {


System.out.println( id + "<<<" );


//根据 ID 查询


User user = userService.queryUserById( id );


//user--json


return user;


}


@GetMapping("userOne/{name}")


@ApiOperation(value = "根据用户名查询用户记录")


@ApiImplicitParam(name = "userName", value = "查询参数", required = true, paramType = "path")


public User sayUserOne(@PathVariable String name) {


System.out.println( name + "<<<" );


//根据 ID 查询


User user = userService.queryUserByName( name );


//user--json


return user;


}


// @PutMapping("add")


// public ResultInfo sayAdd(User user) {


// ResultInfo result=new ResultInfo();


// System.out.println(user + "<<<");


// //根据 ID 查询


// int x= userService.saveUser(user);


// //判断


// if(x>0){


// result.setCode(200);


// result.setMsg("添加 OK");


// }else{


// result.setCode(500);


// result.setMsg("添加失败");


// }


// return result;


// }


@ApiOperation(value = "用户添加")


@ApiImplicitParam(name = "user", value = "用户实体类", dataTy 《一线大厂 Java 面试题解析+后端开发学习笔记+最新架构讲解视频+实战项目源码讲义》无偿开源 威信搜索公众号【编程进阶路】 pe = "User")


@PutMapping("add")


public ResultInfo sayAdd(User user) {


ResultInfo result = new ResultInfo();


System.out.println( user + "<<<" );


//根据 ID 查询


try {


userService.saveUser( user );


} catch (ParamException ex) {


ex.printStackTrace();


//初始化对象信息


result.setCode( ex.getCode() );

用户头像

还未添加个人签名 2022.04.13 加入

还未添加个人简介

评论

发布
暂无评论
API 文档构建工具 - Swagger2简单应用_Java_爱好编程进阶_InfoQ写作社区