Swagger中的常用注解

1、简介

​ Swagger是为了解决企业中接口（api）中定义统一标准规范的文档生成工具。很多采用前后端分离的模式，前端只负责调用接口，进行渲染，前端和后端的唯一联系，变成了API接口。因此，API文档变得越来越重要。swagger是一个方便我们更好的编写API文档的框架，而且swagger可以模拟http请求调用。

2、常用注解与示例

• @Api（）用于类：表示标识这个类是swagger的资源

• 
  

  @Api("用于类")
   @Controller
   public class swaggerTest(){
   }
  

• @ApiOperation（）用于方法：表示一个http请求的操作

• 
  

  @Api("ApiOperation测试")
  @Controller
  public class swaggerTest(){
      @ApiOperation(value = "apiOperationTest", notes = "apiOperation测试")
      public void apiOperationSwaggerTest(){
      }
  }
  

• @ApiParam（）：用于方法，参数，字段说明：表示对参数的添加元数据（说明或是否必填等）

• 
  

  @Api("ApiParam测试")
  @Controller
  public class swaggerTest(){
      @ApiOperation(value = "apiOperationTest", notes = "apiOperation测试")
      public void apiOperationTest(@ApiParam(name = "id", value = "1", required = true) Integer id){
      }
  }
  

• @ApiModel（）用于类：表示对类进行说明，用于参数用实体类接收

• 
  

  @ApiModel(description = "实体类", value = "实体类")
  public class City implements Serializable {
     
  }
  

• @ApiModelProperty（）用于方法，字段：表示对model属性的说明或者是数据操作更改

• 
  

  @ApiModel(description = "实体类", value = "实体类")
  public class City implements Serializable {
      @ApiModelProperty(name = "id", value = "编号", required = false, exmaple = "1")
      private int id;
  }
  

• @ApiIgnore（）用于类，方法，方法参数：表示这个方法或者类被忽略

• 
  

  @ApiIgnore
  @Api(tags = {"Xxx控制类"})
  @RestController
  @RequestMapping("/xxx")
  public class XxxController {
  	
  }
  

• @ApiImplicitParam（）用于方法：表示单独的请求参数

  @ApiImplicitParams（）用于方法，包含多个@ApiImplicitParam

• 
  

  @Api("测试1")
    @Controller
    public class swaggerTest(){
        @ApiOperation(value = "apiOperationTest", notes = "apiOperation测试")
        @ApiImplicitParams({@ApiImplicitParam(name = "id", value = "id", required = true, dataType = "Integer", paramType = "query"),
                          @ApiImplicitParam(name = "name", value = "name", required = true, dataType = "String", paramType = "query")
      })
        public void apiOperationSwaggerTest(Integer id, String name){
        }
    }

实例

package com.tfjybj.integral.provider.controller;

import com.dmsdbj.cloud.tool.business.IntegralResult;
import com.tfjybj.integral.model.AuthLoginModel;
import com.tfjybj.integral.model.DingCodeLoginModel;
import com.tfjybj.integral.provider.service.AuthService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * 调用权限接口
 *
 * @author Promsing(张有博)
 * @version 1.0.0
 * @since 2021/12/18 - 11:39
 */
@Api(tags = {"调用权限接口"})
@RequestMapping(value = "/authController")
@RestController
public class AuthController {

    @Autowired
    private AuthService authService;
    @ApiOperation(value = "登录")
    @PostMapping("login")
    public IntegralResult authLogin(@RequestBody AuthLoginModel authLoginModel){

        Object integralResult = authService.authLogin(authLoginModel);

        if (integralResult==null){
            return IntegralResult.build(IntegralResult.FAIL,"用户不存在",integralResult);
        }
        return IntegralResult.build(IntegralResult.SUCCESS,"返回成功",integralResult);
    }
    @ApiOperation(value = "免密码登录")
    @PostMapping("dingCodeLogin")
    public IntegralResult dingCodeLogin(@RequestBody DingCodeLoginModel dingCodeLoginModel){

        Object integralResult = authService.dingCodeLogin(dingCodeLoginModel);

        if (integralResult==null){
            return IntegralResult.build(IntegralResult.FAIL,"用户不存在",integralResult);
        }
        return IntegralResult.build(IntegralResult.SUCCESS,"返回成功",integralResult);
    }

}

：