# :-: **系統接口標準范例** 在現在的開發過程中我們經常都是以口口相傳的方式來進行前后端的聯調，而接口文檔很大一部分都只停留在了說說而已的地步，或者寫了代碼再寫文檔。 還有一點就是文檔的修改，定義好的接口并不是一成不變的，可能在開發過程中文檔修改不止一次的變化，這個時候就會很難受了。 只要不是強制性要求，沒人會愿意寫這東西，而且在寫的過程中，一個字母的錯誤就會導致聯調時候的很大麻煩，但是通過\`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 | 用在返回對象類上 |