怎么使用@Api注解生成API接口文档呢

通过注解可以控制生成的接口文档，使接口文档拥有更好的可读性，常用注解如下：

注解	说明
@Api	用在类上，描述Controller的作用
@ApiOperation	用在方法上，说明方法的用途、作用
@ApiParam	用在方法的参数上，描述单个形参的含义
@ApiImplicitParam	用在方法上，描述单个形参的含义，与上面相比使用范围更广
@ApiModel	用在类上，用对象来接收参数或者返回参数，描述类的含义
@ApiModelProperty	用在类的属性上，用对象来接收参数或者返回参数，描述字段的含义

示例：

NursingProjectController控制层代码

package com.zzyl.controller;  
  
import com.zzyl.base.PageResponse;  
import com.zzyl.base.ResponseResult;  
import com.zzyl.dto.NursingProjectDto;  
import com.zzyl.service.NursingProjectService;  
import com.zzyl.vo.NursingProjectVo;  
import io.swagger.annotations.Api;  
import io.swagger.annotations.ApiOperation;  
import io.swagger.annotations.ApiParam;  
import org.springframework.beans.factory.annotation.Autowired;  
import org.springframework.web.bind.annotation.*;  
  
import java.util.List;  
  
/**  
* 护理项目Controller类  
*/  
@RestController  
@RequestMapping("/nursing_project")  
@Api(tags = "护理项目管理")  
public class NursingProjectController {  
  
@Autowired  
private NursingProjectService nursingProjectService;  
  
/**  
* 新增护理项目  
*  
* @param nursingProjectDTO 护理项目数据传输对象  
* @return 操作结果  
*/  
@PostMapping  
@ApiOperation("新增护理项目")  
public ResponseResult add(  
@ApiParam(value = "护理项目数据传输对象", required = true)  
@RequestBody NursingProjectDto nursingProjectDTO) {  
nursingProjectService.add(nursingProjectDTO);  
return ResponseResult.success();  
}  
  
/**  
* 根据编号查询护理项目信息  
*  
* @param id 护理项目编号  
* @return 护理项目信息  
*/  
@GetMapping("/{id}")  
@ApiOperation("根据编号查询护理项目信息")  
public ResponseResult<NursingProjectVo> getById(  
@ApiParam(value = "护理项目编号", required = true)  
@PathVariable("id") Long id) {  
NursingProjectVo nursingProjectVO = nursingProjectService.getById(id);  
return ResponseResult.success(nursingProjectVO);  
}  
  
/**  
* 分页查询护理项目列表  
*  
* @param name 护理项目名称  
* @param status 状态：0-禁用，1-启用  
* @param pageNum 当前页码  
* @param pageSize 每页显示数量  
* @return 护理项目列表  
*/  
@GetMapping  
@ApiOperation("分页查询护理项目列表")  
public ResponseResult<PageResponse<NursingProjectVo>> getByPage(  
@ApiParam(value = "护理项目名称")  
@RequestParam(value = "name", required = false) String name,  
@ApiParam(value = "状态：0-禁用，1-启用")  
@RequestParam(value = "status", required = false) Integer status,  
@ApiParam(value = "当前页码")  
@RequestParam(value = "pageNum", defaultValue = "1") Integer pageNum,  
@ApiParam(value = "每页显示数量")  
@RequestParam(value = "pageSize", defaultValue = "10") Integer pageSize) {  
PageResponse<NursingProjectVo> nursingProjectPageInfo = nursingProjectService.getByPage(name, status, pageNum, pageSize);  
return ResponseResult.success(nursingProjectPageInfo);  
}  
  
/**  
* 更新护理项目信息  
*  
* @param nursingProjectDTO 护理项目数据传输对象  
* @return 操作结果  
*/  
@PutMapping  
@ApiOperation("更新护理项目信息")  
public ResponseResult update(  
@ApiParam(value = "护理项目数据传输对象", required = true)  
@RequestBody NursingProjectDto nursingProjectDTO) {  
nursingProjectService.update(nursingProjectDTO);  
return ResponseResult.success();  
}  
  
/**  
* 删除护理项目信息  
*  
* @param id 护理项目编号  
* @return 操作结果  
*/  
@DeleteMapping("/{id}")  
@ApiOperation("删除护理项目信息")  
public ResponseResult deleteById(  
@ApiParam(value = "护理项目编号", required = true)  
@PathVariable("id") Long id) {  
NursingProjectVo nursingProjectVO = nursingProjectService.getById(id);  
if (nursingProjectVO == null) {  
return ResponseResult.error();  
}  
nursingProjectService.deleteById(id);  
return ResponseResult.success();  
}  
  
@PutMapping("/{id}/status/{status}")  
@ApiOperation("启用/禁用护理项目")  
public ResponseResult enableOrDisable(  
@ApiParam(value = "护理项目编号", required = true)  
@PathVariable Long id,  
@ApiParam(value = "状态：0-禁用，1-启用", required = true)  
@PathVariable Integer status) {  
nursingProjectService.enableOrDisable(id, status);  
return ResponseResult.success();  
}  
  
@ApiOperation("查询所有护理项目")  
@GetMapping("/all")  
public ResponseResult<List<NursingProjectVo>> getAllNursingProject() {  
return ResponseResult.success(nursingProjectService.listAll());  
}  
}  

NursingProjectDto

@Data  
@ApiModel(value = "护理项目参数接收实体")  
public class NursingProjectDto extends BaseDto {  
  
@ApiModelProperty(value = "护理名称")  
private String name;  
  
@ApiModelProperty(value = "排序字段")  
private Integer orderNo;  
  
@ApiModelProperty(value = "单位")  
private String unit;  
  
@ApiModelProperty(value = "价格")  
private BigDecimal price;  
  
@ApiModelProperty(value = "图片")  
private String image;  
  
@ApiModelProperty(value = "护理要求")  
private String nursingRequirement;  
  
@ApiModelProperty(value = "状态（0：禁用，1：启用）")  
private Integer status;  
}  

BaseDto

package com.zzyl.base;  
  
import com.fasterxml.jackson.annotation.JsonIgnore;  
import io.swagger.annotations.ApiModelProperty;  
import lombok.Data;  
  
import java.io.Serializable;  
import java.util.HashMap;  
import java.util.Map;  
  
/**  
* Entity基类  
*  
*  
*/  
@Data  
public class BaseDto implements Serializable  
{  
private static final long serialVersionUID = 1L;  
  
/**  
* 主键  
*/  
@ApiModelProperty(value = "主键")  
private Long id;  
  
/** 搜索值 */  
@JsonIgnore  
private String searchValue;  
  
/** 备注 */  
@ApiModelProperty(value = "备注")  
private String remark;  
  
/** 请求参数 */  
@JsonIgnore  
private Map<String, Object> params;  
  
public Map<String, Object> getParams()  
{  
if (params == null)  
{  
params = new HashMap<>();  
}  
return params;  
}  
  
public void setParams(Map<String, Object> params)  
{  
this.params = params;  
}  
}  

NursingProject

/**  
* 护理项目实体类  
*/  
@Data  
@ApiModel(description = "护理项目实体类")  
public class NursingProject extends BaseEntity {  
  
/**  
* 护理名称  
*/  
@ApiModelProperty(value = "护理名称")  
private String name;  
  
/**  
* 排序  
*/  
@ApiModelProperty(value = "排序")  
private Integer orderNo;  
  
/**  
* 单位  
*/  
@ApiModelProperty(value = "单位")  
private String unit;  
  
/**  
* 价格  
*/  
@ApiModelProperty(value = "价格")  
private BigDecimal price;  
  
/**  
* 图片路径  
*/  
@ApiModelProperty(value = "图片路径")  
private String image;  
  
/**  
* 护理要求  
*/  
@ApiModelProperty(value = "护理要求")  
private String nursingRequirement;  
  
/**  
* 状态 （0：禁用，1：启用）  
*/  
@ApiModelProperty(value = "状态 （0：禁用，1：启用）")  
private Integer status;  
}  

BaseEntity

/**  
* @Description：实体基础类  
*/  
@Data  
@NoArgsConstructor  
@ApiModel(description = "实体基础类")  
public class BaseEntity implements Serializable {  
/**  
* 主键  
*/  
@ApiModelProperty(value = "主键")  
public Long id;  
  
/**  
* 创建时间  
*/  
@ApiModelProperty(value = "创建时间")  
public LocalDateTime createTime;  
  
/**  
* 更新时间  
*/  
@ApiModelProperty(value = "更新时间")  
public LocalDateTime updateTime;  
  
/**  
* 创建人  
*/  
@ApiModelProperty(value = "创建人")  
private Long createBy;  
  
/**  
* 更新人  
*/  
@ApiModelProperty(value = "更新人")  
private Long updateBy;  
  
/**  
* 备注  
*/  
@ApiModelProperty(value = "备注")  
private String remark;  
  
/**  
* 创建人  
*/  
@ApiModelProperty(value = "创建人")  
private String creator;  
  
/**  
* 更新人  
*/  
@ApiModelProperty(value = "更新人")  
private String updater;  
  
/**  
* 请求参数 (JsonIgnore is used to exclude it from Swagger docs)  
*/  
@JsonIgnore  
private Map<String, Object> params;  
  
public Map<String, Object> getParams() {  
if (params == null) {  
params = new HashMap<>();  
}  
return params;  
}  
}  

在线文档调试

启动本地服务后，访问地址：http://localhost:9995/doc.html