Spring Boot集成SpringFox 3：生成Swagger接口文檔

關注程序員的故事，一塊兒用技術改變世界html

SpringFox介紹java

SpringFox 是一個開源的API Doc的框架，它的前身是swagger-springmvc，能夠將咱們的Controller中的方法以文檔的形式展示。官方定義爲： Automated JSON API documentation for API's built with Spring。

Swagger介紹程序員

Swagger是一個規範和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。整體目標是使客戶端和文件系統做爲服務器以一樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，容許API來始終保持同步。web

SpringFox使用教程

第一步： Maven框架機構Springboot項目，依賴SpringFox包：

<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version></dependency>

第二步： 在Springboot項目啓動添加註解@EnableOpenApi:

package com.missye.swagger;
import org.springframework.boot.SpringApplication;import org.springframework.boot.autoconfigure.SpringBootApplication;import springfox.documentation.oas.annotations.EnableOpenApi;
@EnableOpenApi@SpringBootApplicationpublic class SwaggerApplication {
 public static void main(String[] args) { SpringApplication.run(SwaggerApplication.class, args); }
}

第三步 ：建立測試API接口，包含實體類/控制器

用戶實體類：

package com.missye.swagger;
import io.swagger.annotations.ApiModel;import io.swagger.annotations.ApiModelProperty;import lombok.AllArgsConstructor;import lombok.Data;import lombok.NoArgsConstructor;
/** * 用戶實體類信息 * @author missye * @since 2020/07/21 */@Data@NoArgsConstructor@AllArgsConstructor@ApiModel("用戶基本信息")public class SysUser {
 /** * 用戶名 */ @ApiModelProperty("用戶名") private String userName; /** * 用戶暱稱 */ @ApiModelProperty("用戶暱稱") private String nickName; /** * 郵件 */ @ApiModelProperty("郵件") private String email; /** * 手機號 */ @ApiModelProperty("手機號") private String mobile;
}

用戶控制器：spring

package com.missye.swagger;
import io.swagger.annotations.Api;import io.swagger.annotations.ApiOperation;import org.springframework.web.bind.annotation.*;
import java.util.ArrayList;import java.util.List;
/** * 用戶控制器 * @author missye * @since 2020/07/21 */@Api(tags = "用戶管理控制器")@RestController@RequestMapping("/sysUser")public class SysUserController {
 /** * 保存用戶信息 * @param sysUser * @return ResultT<java.lang.String> * @author missye * @since 2020/7/21 */ @ApiOperation("保存用戶信息") @PostMapping("/saveSysUser") public ResultT<String> saveSysUser(@RequestBody SysUser sysUser) { //保存用戶信息
 return ResultT.ok("用戶保存成功！"); }
 /** * 獲取用戶信息 * @param sysUser * @return ResultT<com.missye.swagger.SysUser> * @author missye * @since 2020/7/21 */ @ApiOperation("獲取用戶信息") @PostMapping("/getSysUser") public ResultT<SysUser> getSysUser(@RequestBody SysUser sysUser) { return ResultT.ok(new SysUser()); }
 /** * 獲取全部用戶信息 * @param * @return ResultT<java.util.List < com.missye.swagger.SysUser>> * @author missye * @since 2020/7/21 */ @ApiOperation("獲取全部用戶信息") @PostMapping("/getAllSysUser") public ResultT<List<SysUser>> getAllSysUser() { return ResultT.ok(new ArrayList<SysUser>()); }
}

API統一響應工具類：springboot

package com.missye.swagger;
import lombok.Data;
import java.io.Serializable;import java.util.List;
/** * Api響應結果信息 * @author missye * @program springboot-company * @since 2020-05-16 09:42 **/public class ResultT<T> implements Serializable {
 private static final long serialVersionUID = 9142315231410107803L;
 /** * 成功狀態 * @ignore */ private static final Integer SUCCESS = 0; /** * 成功狀態 * @ignore */ private static final String MSG_SUCCESS = "業務處理成功"; /** * 失敗狀態碼 * @ignore */ private static final Integer FAIL = -1; /** * 失敗狀態碼 * @ignore */ private static final String MSG_FAIL = "業務處理失敗"; /** * 業務錯誤碼 */ private Integer code; /** * 描述 */ private String msg; /** * 結果集 */ private T content;
 /** * 業務處理成功，但無業務數據 */ public ResultT() { this(SUCCESS, MSG_SUCCESS, null); }
 /** * 業務處理成功，但有業務數據 * @param content 結果數據 */ public ResultT(T content) { this(SUCCESS, MSG_SUCCESS, content); }
 /** * 默認處理時自定義業務編碼，沒有業務數據 * @param code 錯誤編碼 * @param msg 提示消息 */ public ResultT(int code, String msg) { this(code, msg, null); }
 /** * 默認處理時，自定義業務編碼消息和業務數據 * @param code 錯誤編碼 * @param msg 提示消息 */ public ResultT(int code, String msg, T content) { this.setCode(code); this.setMsg(msg); this.setContent(content); }
 /** * 自定義返回錯誤的消息，無業務數據 * @param code 錯誤編碼 * @param msg 錯誤消息 * @return 錯誤結果 */ public static <T> ResultT<T> error(int code, String msg) { return new ResultT<>(code, msg, null); }
 /** * 返回默認錯誤. 有業務數據 * @param msg 錯誤消息(業務錯誤) * @return 錯誤結果 */ public static ResultT<String> error(String msg) { return new ResultT<>(FAIL, msg, null); }
 /** * 返回默認錯誤，無業務數據 * @return 錯誤結果 */ public static <T> ResultT<T> error() { return error(FAIL, MSG_FAIL); }
 /** * 返回自定義成功的消息，無業務數據 * @param code 自定義成功編碼 * @param msg 正確消息 * @return 正確結果 */ public static <T> ResultT<T> ok(Integer code, String msg) { return new ResultT<T>(code, msg); }
 /** * 成功默認成功狀態，有業務數據 * @param content 業務數據能夠是List、Entity等數據 * @return 正確結果 */ public static <T> ResultT<T> ok(T content) { return new ResultT<>(content); }
 /** * 返回默認成功的狀態信息，無業務數據 * @return 正確結果 */ public static <T> ResultT<T> ok() { return new ResultT<>(); }
 /** * 根據業務條件返回成功或失敗的結果,必須保證成功和失敗返回的類型是一致的 * @param checked 檢查條件 * @param sucess 條件爲true時成功返回的消息 * @param fail 條件爲false的失敗返回的消息 * @return 返回結果 */ public static ResultT<String> on(boolean checked, String sucess, String fail) { return checked ? ResultT.ok(SUCCESS, sucess) : ResultT.error(FAIL, fail); }
 /** * 獲取結果編碼 * @return 結果編碼 * @author zengxueqi */ public Integer getCode() { return code; }
 /** * 設置結果編碼 * @param code 結果編碼 * @return * @author missye */ public ResultT<T> setCode(Integer code) { this.code = code; return this; }
 /** * 獲取消息提示 * @return 消息提示 * @author missye */ public String getMsg() { return msg; }
 /** * 設置消息提示 * @param msg 消息提示 * @return 對象 * @author missye */ public ResultT<T> setMsg(String msg) { this.msg = msg; return this; }
 /** * 獲取業務數據 * @return 業務數據 * @author zengxueqi */ public T getContent() { return content; }
 /** * 設置業務數據 * @param content 業務數據 * @return 結果數據 * @author missye */ public ResultT<T> setContent(T content) { this.content = content; return this; }}

第四步： 啓動Springboot項目，訪問Swagger頁面：http://localhost:8080/swagger-ui/index.html

打開其中一個API接口文檔，能夠包含接口的請求與響應的詳細信息，而且支持在線接口測試。

註解說明
服務器

本文測試案例總共用到4個SpringFox註解，以下：

@Api：用在類上，說明該類的做用。能夠標記一個Controller類作爲swagger 文檔資源。
@ApiOperation：用在方法上，說明方法的做用，每個url資源的定義。
@ApiModel：描述一個Model的信息。
@ApiModelProperty：描述一個model的屬性。

以上就是Springboot集成SpringFox生成Swagger接口文檔的詳細教程，雖然Swagger存在代碼入侵性，可是在Api接口測試方面，它仍是很是的不錯，目前還多大公司使用改插件，可見其便捷性了。

本文分享自微信公衆號 - 程序猿的故事（zengxueqi-music）。
若有侵權，請聯繫 support@oschina.cn 刪除。
本文參與「OSC源創計劃」，歡迎正在閱讀的你也加入，一塊兒分享。微信