快捷導(dǎo)航

SpringBoot集成Swagger2生成接口文檔的方法示例

更新時(shí)間：2018年12月20日 10:49:26 作者：名字想好沒

我們提供Restful接口的時(shí)候，API文檔是尤為的重要，它承載著對(duì)接口的定義，描述等，本文主要介紹了SpringBoot集成Swagger2生成接口文檔的方法示例，需要的朋友們下面隨著小編來一起學(xué)習(xí)學(xué)習(xí)吧

我們提供Restful接口的時(shí)候，API文檔是尤為的重要，它承載著對(duì)接口的定義，描述等。它還是和API消費(fèi)方溝通的重要工具。在實(shí)際情況中由于接口和文檔存放的位置不同，我們很難及時(shí)的去維護(hù)文檔。個(gè)人在實(shí)際的工作中就遇到過很多接口更新了很久，但是文檔卻還是老版本的情況，其實(shí)在這個(gè)時(shí)候這份文檔就已經(jīng)失去了它存在的意義。而 Swagger 是目前我見過的最好的API文檔生成工具，使用起來也很方便，還可以直接調(diào)試我們的API。我們今天就來看下 Swagger2 與 SpringBoot 的結(jié)合。

準(zhǔn)備工作

一個(gè)SpringBoot項(xiàng)目，可以直接去官網(wǎng) 生成一個(gè)demo 。

一個(gè)用戶類。

package cn.itweknow.springbootswagger.model;

import java.io.Serializable;

/**
 * @author ganchaoyang
 * @date 2018/12/19 10:29
 * @description
 */
public class User implements Serializable {

 private Integer id;

 private String name;

 private String password;

 private String email;
}

項(xiàng)目依賴

Web Service肯定是一個(gè)Web項(xiàng)目，所以我們這里依賴了 spring-boot-starter-web 包，其他兩個(gè)包就是和 Swagger 相關(guān)的包了。

<dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-web</artifactId>
</dependency>

<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger2</artifactId>
 <version>2.9.2</version>
</dependency>

<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger-ui</artifactId>
 <version>2.9.2</version>
</dependency>

Swagger配置

Springfox Docket實(shí)例為Swagger配置提供了便捷的配置方法以及合理的默認(rèn)配置。我們將通過創(chuàng)建一個(gè)Docket實(shí)例來對(duì)Swagger進(jìn)行配置，具體配置如下所示。

@Configuration
@EnableSwagger2
public class SwaggerConfig extends WebMvcConfigurationSupport {

 @Bean
 public Docket productApi() {
  return new Docket(DocumentationType.SWAGGER_2).select()
    // 掃描的包路徑
    .apis(RequestHandlerSelectors.basePackage("cn.itweknow.springbootswagger.controller"))
    // 定義要生成文檔的Api的url路徑規(guī)則
    .paths(PathSelectors.any())
    .build()
    // 設(shè)置swagger-ui.html頁面上的一些元素信息。
    .apiInfo(metaData());
 }

 private ApiInfo metaData() {
  return new ApiInfoBuilder()
    // 標(biāo)題
    .title("SpringBoot集成Swagger2")
    // 描述
    .description("這是一篇博客演示")
    // 文檔版本
    .version("1.0.0")
    .license("Apache License Version 2.0")
    .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0")
    .build();
 }

 @Override
 protected void addResourceHandlers(ResourceHandlerRegistry registry) {
  registry.addResourceHandler("swagger-ui.html")
    .addResourceLocations("classpath:/META-INF/resources/");

  registry.addResourceHandler("/webjars/**")
    .addResourceLocations("classpath:/META-INF/resources/webjars/");
 }
}

上述代碼中的addResourceHandlers方法添加了兩個(gè)資源處理程序，這段代碼的主要作用是對(duì)Swagger UI的支持。

API文檔

好了，到這一步，我們已經(jīng)在一個(gè)SpringBoot項(xiàng)目中配置好了Swagger。現(xiàn)在，我們就來看一下如何去使用他。首先我們定義了一個(gè) Controller 并提供了兩個(gè)接口：

通過用戶id獲取用戶
用戶登錄

@RestController
@RequestMapping("/user")
@Api(description = "用戶相關(guān)接口")
public class UserController {

 /**
  * 通過id查詢用戶
  * @return
  */
 @RequestMapping(value = "/get", method = RequestMethod.GET)
 @ApiOperation("根據(jù)id獲取用戶")
 public User getUserById(@ApiParam(value = "用戶id") Integer id) {
  return new User();
 }

 @RequestMapping(value = "/login", method = RequestMethod.POST)
 @ApiOperation("用戶登錄")
 public User login(@RequestBody User user) {
  return new User();
 }
}

相信大家都注意到了，這個(gè) Controller 里面多了很多新的注解，比如說 @Api , @ApiOperation 等，下面我們就來一一解釋一下。

@Api,這個(gè)注解是用在Controller類上面的，可以對(duì)Controller做必要的說明。
@ApiOperation，作用在具體的方法上，其實(shí)就是對(duì)一個(gè)具體的API的描述。
@ApiParam，對(duì)API參數(shù)的描述。

到這里，其實(shí)我們的Swagger就已經(jīng)可以有效果了，讓我們將項(xiàng)目運(yùn)行起來先看看效果。訪問 http://localhost:8080/swagger-ui.html 即可。

Model

在上面的圖中可以看到在頁面的下方有一個(gè)Models的標(biāo)簽，那么這個(gè)是啥呢。其實(shí)這個(gè)就是我們API中出現(xiàn)的一些對(duì)象的文檔，我們也可以通過注解來對(duì)這些對(duì)象中的字段做一些說明，以方便使用者理解。以文章開頭提到的 User 類來做一個(gè)說明。

@ApiModel("用戶實(shí)體")
public class User implements Serializable {

 @ApiModelProperty(value = "用戶id")
 private Integer id;

 @ApiModelProperty(value = "用戶名稱", required = true)
 private String name;

 @ApiModelProperty(value = "密碼", required = true)
 private String password;

 @ApiModelProperty(value = "用戶郵箱")
 private String email;
}

我們來看一下 User 類在Swagger上是如何展示的：