-
在團隊開發中，一個好的 API 文檔不但可以減少大量的溝通成本，還可以幫助一位新人快速上手業務。傳統的做法是由開發人員創建一份 RESTful API 文檔來記錄所有的接口細節，並在程序員之間代代相傳。
-
Swagger2 的出現就是爲了從根本上解決上述問題。它作爲一個規範和完整的框架，可以用於生成、描述、調用和可視化 RESTful 風格的 Web 服務：
-
1.接口文檔在線自動生成，文檔隨接口變動實時更新，節省維護成本
-
2.支持在線接口測試，不依賴第三方工具
-
-
Swagger 通過註解定製接口對外展示的信息，這些信息包括接口名、請求方法、參數、返回信息等。更多註解類型：
參考鏈接寫的非常詳細
參考鏈接寫的非常詳細：https://blog.csdn.net/HiBoyljw/article/details/81110553
自己整理：
@Api：
修飾整個類，描述Controller的作用
@ApiOperation：
描述一個類的一個方法，或者說一個接口
@@PostMapping("/app/{user_id}/")
@ApiOperation(value = “創建topic”,notes = “創建topic”,response = KafkaTopicBean.class)
@ApiParam：
單個參數描述
@@PostMapping("/app/{user_id}/")
public Map<String,String> createUser(@ApiParam(value = "用戶id")
@ApiModel：用對象來接收參數
@ApiProperty：用對象接收參數時，描述對象的一個字段
@ApiRespons和@RequestMapping
- @ApiRespons：HTTP響應其中1個描述
@ApiResponse(code = 201,message = "創建用戶成功")
- @@ResponseStatus ：http請求的返回狀態碼
@ResponseStatus(code = HttpStatus.CREATED)
code 和 value一個意思，.這裏@ResponseStatus作用就是改變服務器響應的狀態碼 ,比如一個本是200的請求可以通過@ResponseStatus 改成201/500等等.
常見的幾個狀態碼 HttpStatus.OK 就是 200 , HttpStatus.INTERNAL_SERVER_ERROR 就是 500 等等 ，具體的查看 HttpStatus枚舉 有詳細說明.
@ApiResponses：HTTP響應整體描述
@ApiIgnore：使用該註解忽略這個API
@ApiError ：發生錯誤返回的信息
@ApiImplicitParam：描述一個請求參數，可以配置參數的中文含義，還可以給參數設置默認值
@ApiImplicitParams：描述由多個 @ApiImplicitParam 註解的參數組成的請求參數列表