Springboot中怎麼整合Swagger2框架

摘要：在專案開發中，往往期望做到前後端分離，也就是後端開發人員往往需要輸出大量的服務接口，接口的提供者無論是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如下圖： 

##上圖黃色的地方表示，該介面傳回的範例資料。也就是User的資料結構。 Response Content Type：介面傳回的頭資訊。點選Try it out。如下圖： 

該介面回傳的baody、code碼、回應頭已經成功回傳了。

以上是Springboot中怎麼整合Swagger2框架的詳細內容。更多資訊請關注PHP中文網其他相關文章！