无论是前端还是后端开发,都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力,经常来不及更新。其实无论是前端调用后端,还是后端调用后端,都期望有一个好的接口文档。采用传统的编写接口文档的方式,随着时间推移,版本迭代,接口文档往往很容易就跟不上代码了。云程平台采用Swagger,可以省略了这一步,而且文档出错率近乎于零, 只要你在写代码的时候,稍加几个注解,文档自动生成。
通过Swagger接口规范,你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具,就可以做到生成各种格式的接口文档,生成多种语言的客户端和服务端的代码,以及在线接口调试页面等等。这样,如果按照新的开发模式,在开发新版本或者迭代版本的时候,只需要更新Swagger描述文件,就可以自动生成接口文档和客户端服务端代码,做到调用端代码、服务端代码以及接口文档的一致性。
作为Java届服务端的大一统框架Spring,迅速将Swagger规范纳入自身的标准,建立了Spring-swagger项目,后面改成了现在的Springfox。通过在项目中引入Springfox,可以扫描相关的代码,生成该描述文件,进而生成与代码一致的接口文档和客户端代码。这种通过代码生成接口文档的形式,在后面需求持续迭代的项目中,显得尤为重要和高效。
1、在控制层Controller中添加注解来描述接口信息,以职务管理模块为例说明:
@RestController
@Api(tags = "职务管理接口")
@RequestMapping("/system/sysPosition")
public class SysPositionController extends BaseController<SysPosition, ISysPositionService> {
private static final Logger log = LoggerFactory.getLogger(SysPositionController.class);
@Autowired
private ISysPositionService sysPositionService;
@GetMapping(value = "/list")
//@RequiresPermissions("system:SysPosition:query")
@AutoLog(value = "职务管理-分页查询")
@ApiOperation(value = "职务管理-分页查询", notes = "职务管理-分页查询")
public HttpResult<?> queryPageList(SysPosition sysPosition,
@RequestParam(name="pageNo", defaultValue="1") Integer pageNo,
@RequestParam(name="pageSize", defaultValue="10") Integer pageSize,
HttpServletRequest req) {
QueryWrapper<SysPosition> queryWrapper = QueryBuilder.initQueryWrapper(sysPosition, req.getParameterMap());
Page<SysPosition> page = new Page<SysPosition>(pageNo, pageSize);
IPage<SysPosition> list = sysPositionService.page(page, queryWrapper);
return HttpResult.ok(list);
}
@PostMapping(value = "/add")
@RequiresPermissions("system:SysPosition:add")
@AutoLog(value = "职务管理-添加")
@ApiOperation(value = "职务管理-添加", notes = "职务管理-添加")
public HttpResult<?> add(@RequestBody SysPosition sysPosition) {
sysPositionService.save(sysPosition);
return HttpResult.ok(I18nUtil.message("save.success"));
}
}
2、在model类上添加注解来描述接口信息:
@ApiModel(value = "职务管理对象", description = "职务管理对象")
@TableName("sys_position")
public class SysPosition extends BaseEntity implements Serializable {
private static final long serialVersionUID = 1L;
/**职位名称*/
@Excel(name = "职位名称", width = 15)
@ApiModelProperty(value = "职位名称")
private java.lang.String positionName;
/**职位编码*/
@Excel(name = "职位编码", width = 15)
@ApiModelProperty(value = "职位编码")
private java.lang.String positionCode;
/**职位排序*/
@Excel(name = "职位排序", width = 15)
@ApiModelProperty(value = "职位排序")
private java.lang.Integer positionOrder;
/**职位描述*/
@Excel(name = "职位描述", width = 15)
@ApiModelProperty(value = "职位描述")
private java.lang.String description;
}
经常使用的swagger注解有:
作用范围 |
API注解 |
使用位置 |
协议集描述 |
@Api |
用于controller类上 |
对象属性 |
@ApiModelProperty |
用在出入参数对象的字段上 |
协议描述 |
@ApiOperation |
用在controller的方法上 |
Response集 |
@ApiResponses |
用在controller的方法上 |
Response |
@ApiResponse |
用在 @ApiResponses里边 |
非对象参数集 |
@ApiImplicitParams |
用在controller的方法上 |
非对象参数描述 |
@ApiImplicitParam |
用在@ApiImplicitParams的方法里边 |
描述返回对象的意义 |
@ApiModel |
用在返回对象类上 |
更详细的使用方法请参考:https://www.cnblogs.com/three-fighter/p/12346184.html