Swagger的使用
1 基礎概念
1.1 Swagger的介紹
導語：在平時的開發(fā)中，無論是前端還是后端，都或多或少的被接口文檔折磨過。前端經(jīng)常抱怨后端給的接口文檔與實際不符，后端又覺得寫代碼已經(jīng)夠累了，還要相應的更新接口文檔，更加麻煩。這個時候，如果有一個工具，可以自動的生成多種格式的接口文檔，以及在線調(diào)試頁面等，就剛好符合開發(fā)人的需求。所以Swagger工具就應運而生。
那么問題來了，Swagger到底是什么？
1，Swagger是一款能夠讓開發(fā)人員更好的書寫API文檔的規(guī)范和完整的框架。
2，提供描述、生產(chǎn)、消費和可視化Restful Web Service。
3，是由龐大工具集合支撐的形式化規(guī)范。
1.2 Swagger組件的介紹
Swagger Codegen : 通過Codegen可以將描述文件生成html格式和cwiki形式的接口文檔，同時也能生成多種語言的服務端和客戶端的代碼。支持通過jar包，docker，node等方式在本地化執(zhí)行生成。也可以在后面的Swagger Editor中在線生成。
Swagger Editor ：類似于markendown編輯器的編輯Swagger描述文件的編輯器，該編輯支持實時預覽描述文件的更新效果。也提供了在線編輯器和本地部署編輯器兩種方式。
Swagger UI ：提供了一個可視化的UI頁面展示描述文件。接口的調(diào)用方、測試、項目經(jīng)理等都可以在該頁面中對相關接口進行查閱和做一些簡單的接口請求。該項目支持在線導入描述文件和本地部署UI項目。
2 Swagger 的使用
2.1 添加maven依賴
由于swagger與SpringBoot一起使用的比較多，所以本篇文章所使用的都是SpringBoot與swagger集成。
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.5.22</version>
</dependency>
2.2 添加配置項
在application.properties中添加對應的配置項，開啟Swagger。
swagger.enable=true
2.3 添加配置類
在項目中創(chuàng)建SwaggerConfig.java文件，配置swagger。
@Configuration
@EnableSwagger2
@ConditionalOnProperty(name = "swagger.enable",
havingValue = "true")
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("dataassets-base")
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors
.basePackage("Controller對應的包路經(jīng)"))
.build();
}
?
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Rest API Docs")
.description("api info")
.version("1.0")
.build();
}
}
2.4 添加注解
- 在啟動類
Application.java上添加注解
@EnableSwagger2：表示開啟Swagger
@SpringBootApplication
@EnableSwagger2
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
- 在Controller類上添加的注解：
@api：修飾整個類，描述Controller的作用
@ApiOperation：描述一個類的一個方法，或者說一個接口
@ApiParam：單個參數(shù)描述
@Api(value = "UserController", tags = {"用戶模塊"})
@RestController
@RequestMapping(value = "/user/")
public class UserController{
@Autowired
private UserService userService;
@ApiOperation(value = "根據(jù)userId獲取用戶")
@GetMapping("/queryUserByUserId")
@ResponseBody
public DepartmentDTO queryUserByUserId(
@ApiParam("userId")
@RequestParam(value = "userId",required = false)
String userId) {
// 獲取滿足條件的department
return userService.getUserByUserId(userId);
}
}
- 如果請求參數(shù)是一個對象時，需要在相應的類上添加注解：
@ApiModel：用對象來接收參數(shù)
@ApiModelProperty：用對象接收參數(shù)時，描述對象的一個字段
@ApiModel(value = "UserQuery", description = "查詢用戶條件")
public class UserQuery implements Serializable {
private static final long serialVersionUID = 1L;
@ApiModelProperty("用戶id")
private String userId;
?
@ApiModelProperty("用戶名")
private Long userName;
}
2.5 訪問Swagger UI
在瀏覽器中輸入地址 : http://localhost:8080/swagger-ui.html，即可訪問Swagger UI，進入接口頁面。
3 小結(jié)
本篇文章簡單介紹了Swagger的簡單使用，由于純手打，難免會有紕漏，如果發(fā)現(xiàn)錯誤的地方，請第一時間告訴我，這將是我進步的一個很重要的環(huán)節(jié)。
