swagger常用注解说明

Posted 2023-03-09

参考技术A Api 用在类上，说明该类的作用。可以标记一个Controller类做为swagger 文档资源，使用方式：

与Controller注解并列使用。 属性配置：

在SpringMvc中的配置如下：

ApiOperation：用在方法上，说明方法的作用，每一个url资源的定义,使用方式：

与Controller中的方法并列使用。
属性配置：

在SpringMvc中的配置如下：

ApiParam请求属性,使用方式：

与Controller中的方法并列使用。

属性配置：

在SpringMvc中的配置如下：

ApiResponse：响应配置，使用方式：

与Controller中的方法并列使用。 属性配置：

在SpringMvc中的配置如下：

ApiResponses：响应集配置，使用方式：

与Controller中的方法并列使用。 属性配置：

在SpringMvc中的配置如下：

与Controller中的方法并列使用。 属性配置：

在SpringMvc中的配置如下：

Swagger2 常用注解使用及其说明

目录

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);
   }