本文共 5033 字，大约阅读时间需要 16 分钟。

Swagger是一个开放源代码软件框架，由大型工具生态系统支持，可帮助开发人员设计，构建，记录和使用RESTful Web服务。尽管大多数用户通过Swagger UI工具识别Swagger，但是Swagger工具集包括对自动文档，代码生成和测试用例生成的支持。

1、@Api

@Api 注解用于标注一个Controller（Class）。在默认情况下，Swagger-Core只会扫描解析具有@Api注解的类，而会自动忽略其他类别资源（JAX-RS endpoints，Servlets等等）的注解。

主要属性如下：

实例:

@Controller@RequestMapping(value = "/api/pet", produces = {   APPLICATION_JSON_VALUE, APPLICATION_XML_VALUE})@Api(value = "/pet", description = "Operations about pets")public class PetController {   }

2、@ApiOperation

@ApiOperation 注解在用于对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。

主要属性：

实例：

@RequestMapping(value = "/order/{orderId}", method = GET)  @ApiOperation(      value = "Find purchase order by ID",      notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",      response = Order.class,      tags = {    "Pet Store" })   public ResponseEntity
   
     getOrderById(@PathVariable("orderId") String orderId)      throws NotFoundException {       Order order = storeData.get(Long.valueOf(orderId));    if (null != order) {         return ok(order);    } else {         throw new NotFoundException(404, "Order not found");    }  }
   

3、@ApiOperation

@ApiParam作用于请求方法上，定义api参数的注解。

主要属性：

实例：

public ResponseEntity
   
     getOrderById(      @ApiParam(value = "ID of pet that needs to be fetched", allowableValues = "range[1,5]", required = true)      @PathVariable("orderId") String orderId)
   

3、@ApiImplicitParams、@ApiImplicitParam

• @ApiImplicitParams：用在请求的方法上，包含一组参数说明
• @ApiImplicitParam：对单个参数的说明

主要属性：

实例：

@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")	})	@PostMapping("/login")	public JsonResult login(@RequestParam String mobile, @RequestParam String password,	@RequestParam Integer age){   		//...	    return JsonResult.ok(map);	}

4、@ApiResponses、@ApiResponse

@ApiResponses、@ApiResponse进行方法返回对象的说明。

主要属性：

实例：

@ApiResponses({   		@ApiResponse(code = 200, message = "请求成功"),		@ApiResponse(code = 400, message = "请求参数没填好"),		@ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")	}) 	@ResponseBody	@RequestMapping("/list")	public JsonResult list(@RequestParam String userId) {   		...		return JsonResult.ok().put("page", pageUtil);	}

5、@ApiModel、@ApiModelProperty

@ApiModel用于描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）。

@ApiModelProperty用来描述一个Model的属性。

实例：

@ApiModel(description= "返回响应数据")public class RestMessage implements Serializable{   	@ApiModelProperty(value = "是否成功",required=true)	private boolean success=true;			@ApiModelProperty(value = "错误码")	private Integer errCode;		@ApiModelProperty(value = "提示信息")	private String message;	    @ApiModelProperty(value = "数据")	private Object data;			/* getter/setter 略*/}

6、 @PathVariable

@PathVariable用于获取get请求url路径上的参数，即参数绑定的作用，通俗的说是url中"?"前面绑定的参数。

实例：

@GetMapping("/query/{id}")    private List
   
     queryById( @ApiParam(name = "id", value = "学生id", required = true) @PathVariable("id") Long id) {           List
    
      studentList = studentService.queryById(id);        return studentList;    }
    
   

7、 @RequestParam

@RequestParam用于获取前端传过来的参数，可以是get、post请求，通俗的说是url中"?"后面拼接的每个参数。

实例：

@GetMapping("/query/student")    private List
   
     queryByIdStu( @ApiParam(name = "byId", value = "学生id", required = false) @RequestParam("id") Long id) {           List
    
      studentList = studentService.queryById(id);        return studentList;    }
    
   

参考：

【1】：