簡介
Swagger 是一個規(guī)范和完整的框架未舟，用于生成、描述掂为、調(diào)用和可視化 RESTful 風(fēng)格的 Web 服務(wù)裕膀。總體目標(biāo)是使客戶端和文件系統(tǒng)作為服務(wù)器以同樣的速度來更新勇哗。文件的方法昼扛、參數(shù)和模型緊密集成到服務(wù)器端的代碼，允許 API 來始終保持同步欲诺。Swagger 讓部署管理和使用功能強(qiáng)大的 API 從未如此簡單抄谐。
swagger的接口文檔有兩種風(fēng)格，分別為水平列表和樹形分類扰法。
其中蛹含，水平列表風(fēng)格在接口多起來后，就很不友好塞颁，找起接口來比較麻煩浦箱，所以這里將介紹樹形分類風(fēng)格的swagger。廢話不多說走起祠锣。酷窥。。
目錄結(jié)構(gòu)
首先伴网，案例是基于springboot web項目進(jìn)行講解的蓬推，目錄結(jié)構(gòu)如下：
步驟一 引入依賴
<!-- swaggwe-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<!-- swagger核心包 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- swaggwe增強(qiáng)ui -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
步驟二 新建swagger配置類
@Configuration
//啟用swagger2
@EnableSwagger2
//啟用swagger增強(qiáng)UI
@EnableSwaggerBootstrapUI
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
//這里寫的是API接口所在的包位置
.apis(RequestHandlerSelectors.basePackage("com.ypk.swagger.controller"))
.paths(PathSelectors.any())
.build();
}
}
步驟三 編寫接口
@Api(tags = "測試swagger")
@RestController
@RequestMapping(value = "/swagger")
public class SwaggerController {
@ApiOperation(value = "獲取用戶信息")
@GetMapping(value = "/info")
public Result<User> getInfo() {
return Result.<User>successResponse();
}
@ApiOperation(value = "獲取列表數(shù)據(jù)")
@GetMapping(value = "/list")
public Result<List<User>> getList() {
return Result.<List<User>>successResponse();
}
}
為了更好地做演示，這里建了兩個javabean類澡腾，Result和User沸伏。
@ApiModel(value = "結(jié)果對象")
@Data
@AllArgsConstructor
public class Result<T> {
private static final String successMsg = "請求成功";
private static final String failMsg = "請求失敗";
private int status;
private String message;
private T data;
public static <T> Result<T> successResponse() {
return new Result<T>(200, successMsg, null);
}
public static <T> Result<T> successResponse(T data) {
return new Result<T>(200, successMsg, data);
}
public static <T> Result<T> failResponse() {
return new Result<T>(-1, failMsg, null);
}
public static <T> Result<T> failResponse(int status, T data) {
return new Result<T>(status, failMsg, data);
}
public static <T> Result<T> failResponse(String message, T data) {
return new Result<T>(-1, message, data);
}
public static <T> Result<T> failResponse(int status, String message, T data) {
return new Result<T>(status, message, data);
}
}
@ApiModel(value = "用戶視圖")
@Data
public class User {
private int id;
@ApiModelProperty(value = "用戶名")
private String username;
@ApiModelProperty(value = "年齡")
private int age;
}
這里有關(guān)swagger的注解使用不明白的道友募逞，請看我的另一篇文章《注解篇-Swagger常用注解詳解》，@Api…開頭的都是swagger的注解馋评。
步驟四 啟動項目
啟動項目后放接，在瀏覽器地址欄訪問localhost:8080/doc.html
文檔主頁：
單個接口詳情：
導(dǎo)出離線文檔
若不想開放文檔地址，也可導(dǎo)出離線文檔供更多成員使用留特，導(dǎo)出的離線文檔是Markdown格式的文檔纠脾，可以使用Markdown轉(zhuǎn)word工具轉(zhuǎn)為word文檔，更能使更多人易于理解蜕青。
這里再介紹一款在線Markdown轉(zhuǎn)word工具：
http://tools.jb51.net/aideddesign/markdown_tool
新建一個空白word文檔苟蹈，使用 保留源格式 方式粘貼即可。
至此右核，springboot整合swagger增強(qiáng)版UI接口文檔就完事了慧脱；
若文章對道友您有用，記得點贊評論加關(guān)注我哦：睾取Ａ馀浮！
