Swagger2 常用注解使用及其说明

Posted 2021-09-05 被雨遗忘的夏天

目录

Swagger2 常用注解使用及其说明

1、 Api

2、 ApiModel

3、 ApiModelProperty

4、 ApiParam

5、 ApiOperation

6、 ApiResponse 和 ApiResponses

7、 ApiImplicitParam 和 ApiImplicitParams

---

Swagger2 常用注解使用及其说明

1、 Api

@Api 用在类上，说明该类的作用。可以标记一个 Controller 类作为 Swagger 文档资源。

2、 ApiModel

@ApiModel 用在类上，表示对类进行说明，用于实体类中的参数接收说明。

@Api(tags = "BookController")
@Controller
@ApiModel(value = "com.lishaoyu.BookReview.controller.BookController" ,description = "图书控制类")
public class BookController {

3、 ApiModelProperty

@ApiModelProperty() 用于字段，表示对 model 属性的说明。

 

4、 ApiParam

@ApiParam 用于 Controller 中方法的参数说明。

 @GetMapping("/getUser")
    public SysUser getUserInfo(@ApiParam(value = "用户id",required = true) @RequestParam String id){
        return userService.getUserInfo(id);
   }

5、 ApiOperation

@ApiOperation 用在 Controller 里的方法上，说明方法的作用，每一个接口的定义。

    /**
     * 显示首页
     * @return
     */
    @ApiOperation(value = "显示首页")
    @GetMapping("/")
    public ModelAndView showIndex(){
        ModelAndView mav = new ModelAndView("/index");
        List<Category> categoryList = categoryService.selectAll();
        mav.addObject("categoryList", categoryList);
        return mav;
    }

6、 ApiResponse 和 ApiResponses

@ApiResponse 用于方法上，说明接口响应的一些信息；@ApiResponses 组装了多个 @ApiResponse。

@GetMapping("/getUser")
   @ApiOperation(value = "获取用户信息接口")
   @ApiResponses({ @ApiResponse(code = 0, message = "相应成功", response = SysUser.class) })
   public SysUser getUserInfo(@ApiParam(value = "用户id",required = true) @RequestParam String id){
       return userService.getUserInfo(id);
   }

7、 ApiImplicitParam 和 ApiImplicitParams

用于方法上，为单独的请求参数进行说明。

@GetMapping("/getUser")
    @ApiOperation(value = "获取用户信息接口")
    @ApiResponses({ @ApiResponse(code = 0, message = "相应成功", response = SysUser.class) })
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户id", dataType = "string", paramType = "query",
required = true, defaultValue = "0f09e661-7e80-4e1b-b66a-2e266bb593bf")
   })
    public SysUser getUserInfo(@ApiParam(value = "用户id",required = true) @RequestParam String id){
        return userService.getUserInfo(id);
   }