# :-: **系统接口标准范例** 在现在的开发过程中我们经常都是以口口相传的方式来进行前后端的联调，而接口文档很大一部分都只停留在了说说而已的地步，或者写了代码再写文档。 还有一点就是文档的修改，定义好的接口并不是一成不变的，可能在开发过程中文档修改不止一次的变化，这个时候就会很难受了。 只要不是强制性要求，没人会愿意写这东西，而且在写的过程中，一个字母的错误就会导致联调时候的很大麻烦，但是通过\`Swagger\`，我们可以省略了这一步，而且文档出错率近乎于零， 只要你在写代码的时候，稍加几个注解，文档自动生成。 1、定义接口：所有的接口定义类都要Controller结束。在控制层`Controller`中添加注解来描述接口信息如: ~~~ /** * 功能说明:【客户地址操作】 * 作 者：lihaijun * 创建日期：2018-04-04 */ @RestController @Slf4j @Api(description = "地址管理", tags = "地址管理") @RequestMapping("/address") public class AddressController extends BaseController { @Resource AddressService addressService; } ~~~ 2、在方法中配置接口的标题信息 ~~~ /** * 【添加地址信息】 */ @PostMapping(value = "addressSave") @ApiOperation(value = "添加地址信息", notes="添加地址信息") public BaseResp addressSave(@RequestBody AddressAddReq q ) { return addressService.save(q); } ~~~ API详细说明 | 作用范围 | API | 使用位置 | | --- | --- | --- | | 协议集描述 | @Api | 用于controller类上 | | 对象属性 | @ApiModelProperty | 用在出入参数对象的字段上 | | 协议描述 | @ApiOperation | 用在controller的方法上 | | Response集 | @ApiResponses | 用在controller的方法上 | | Response | @ApiResponse | 用在 @ApiResponses里边 | | 非对象参数集 | @ApiImplicitParams | 用在controller的方法上 | | 非对象参数描述 | @ApiImplicitParam | 用在@ApiImplicitParams的方法里边 | | 描述返回对象的意义 | @ApiModel | 用在返回对象类上 |