摘要：在專案開發中，往往期望做到前後端分離，也就是後端開發人員往往需要輸出大量的服務接口，接口的提供者無論是Java還是PHP等語言，往往會要花費一定的精力去寫接口文檔，例如A接口的地址、需要傳遞參數情況、返回值的JSON資料格式以及每一個字段說明、當然還要考慮HTTP請求頭、請求內容等資訊。隨著專案的進度快速高速的迭代，後端輸出的介面往往會面臨修改、修復等問題，也意味著介面文件也要進行對應的調整。介面文件的維護度以及可讀性就大大下降。
既然介面文件需要花費精力去維護，還要適當的進行面對面交流溝通，我們何不想一個辦法，第一：可以不用寫接口文檔；第二：前端與後端溝通接口問題的時候，後端是否可以提供一個URL，在這個URL中羅列出所有可以調用的服務接口，並在每個服務接口中羅列出參數的說明，返回值的說明，第三：後端接口如果能模擬呼叫就所有問題都解決了。本文我們將重點放在Sringboot中整合Swagger2框架。
1.1. 加入Swagger2依賴
在專案的pom.xml檔案中增加如下的依賴。
<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>
首先，我們需要建立一個啟動類，程式碼如下：
@SpringBootApplication
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}然後在上述類別的同級目錄中新建swagger2的設定類別如下所示：
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.shareniu.web"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("跟着分享牛学习Springboot源码分析系列课程")
.description("更多Spring Boot相关文章请关注分享牛的博客")
.termsOfServiceUrl("http://www.shareniu.com/")
.contact("牛牛")
.license("Copyright 2017-2018 分享牛")
.version("1.0")
.build();
}
}@Configuration制定了spring要載入這個類，@EnableSwagger2註解要開啟Swagger功能。
上述的ApiInfo最終都會展現在前端，我們使用了掃描套件的方式配置配置，也就是RequestHandlerSelectors.basePackage。在這個套件以及子包中的控制器最終都是產生API文件。 （除了被@ApiIgnore註解指定的請求）。
1.2. 新增文件說明
上述的類別宣告之後，我們其實可以直接呼叫了，但是為了增加文件的可讀性，我們還是需要在介面中增加一些說明，我們先寫一個控制器如下所示：
@RestController
@RequestMapping(value="/users")
public class UserController {
static Map<long> users = Collections.synchronizedMap(new HashMap<long>());
static {
User user = new User();
user.setAge(18);
user.setId(1L);
user.setName("aa");
users.put(1L, user);
}
@ApiOperation(value="获取所有用户列表", notes="")
@RequestMapping(value={""}, method=RequestMethod.GET)
public List<user> getUserList() {
List<user> r = new ArrayList<user>(users.values());
return r;
}
@ApiOperation(value="创建新的用户", notes="根据User对象创建用户")
@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
@RequestMapping(value="", method=RequestMethod.POST)
public String postUser(@RequestBody User user) {
users.put(user.getId(), user);
return "success";
}
@ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
@RequestMapping(value="/{id}", method=RequestMethod.GET)
public User getUser(@PathVariable Long id) {
return users.get(id);
}
@ApiOperation(value="更新用户详细信息", notes="根据url的id来指定更新对象")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),
@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
})
@RequestMapping(value="/{id}", method=RequestMethod.PUT)
public String putUser(@PathVariable Long id, @RequestBody User user) {
User u = users.get(id);
u.setName(user.getName());
u.setAge(user.getAge());
users.put(id, u);
return "success";
}
@ApiOperation(value="删除已存在的用户", notes="根据url的id来指定删除对象")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
@RequestMapping(value="/{id}", method=RequestMethod.DELETE)
public String deleteUser(@PathVariable Long id) {
users.remove(id);
return "success";
}
}</user></user></user></long></long> @ApiOperation：用來描述該介面的作用。可透過此註解說明介面的職責、回傳頭資訊、方法的請求方式（"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"）、協定（ http , https, ws, wss）、http狀態碼。
@ApiImplicitParam：用來增加參數說明。可以設定參數的名稱、是否為必填項、參數的描述資訊、是否唯讀等。
上述程式碼提交之後，啟動springboot，訪問http://127.0.0.1:8080/swagger-ui.html
為兩個部分，上一個部分是透過Swagger2類配置出來的，下半部是UserController類別中的介面文件。
這裡我們以/user為例進行說明：
點選/user如下圖：
以上是Springboot中怎麼整合Swagger2框架的詳細內容。更多資訊請關注PHP中文網其他相關文章！
