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

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

文章目錄

• 一、SpringBoot工程創(chuàng)建
• 二、工程配置
• • 2.1. pom依賴配置
  • 2.2. Swagger2配置
• 三、創(chuàng)建接口
• 四、創(chuàng)建實體類
• 五、Swagger2 APL介紹
• 六、頁面效果
• 七、API驗證測試
• • 7.1. 獲取用戶列表接口
  • 7.2. 創(chuàng)建用戶
  • 7.3. 根據(jù)用戶id,獲取用戶詳細(xì)信息
  • 7.4. 根據(jù)用戶id,更新用戶詳細(xì)信息
  • 7.5. 根據(jù)用戶id,刪除用戶信息

一、SpringBoot工程創(chuàng)建

二、工程配置

2.1. pom依賴配置

<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"><modelVersion>4.0.0</modelVersion><parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>2.1.9.RELEASE</version><relativePath/> <!-- lookup parent from repository --></parent><groupId>com.gblfy</groupId><artifactId>springboot-swagger2</artifactId><version>0.0.1-SNAPSHOT</version><name>springboot-swagger2</name><description>Spring Boot整合Swagger2</description><properties><!--編碼設(shè)置--><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding><!--JDK版本--><java.version>1.8</java.version></properties><dependencies><!--Spring Boot整合Swagger2 Start--><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><!--Spring Boot整合Swagger2 End--><!--Springmvc 啟動器--><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><!--生成get/set等--><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><version>1.18.10</version></dependency><!--單元測試--><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency></dependencies><build><plugins><!--maven編譯打包插件--><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin></plugins></build></project>

2.2. Swagger2配置

• 提供一個Docket的Bean即可

package com.gblfy.springbootswagger2.config;import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2;/*** @author gblfy* @ClassNme SwaggerConfig* @Description SwaggerConfig 配置bean類* @Date 2019/11/5 20:19* @version1.0*/ @Configuration @EnableSwagger2 public class SwaggerConfig {/*** 創(chuàng)建一個Docket對象* 調(diào)用select()方法，* 生成ApiSelectorBuilder對象實例，該對象負(fù)責(zé)定義外漏的API入口* 通過使用RequestHandlerSelectors和PathSelectors來提供Predicate，在此我們使用any()方法，將所有API都通過Swagger進(jìn)行文檔管理** @return*/@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).pathMapping("/").select().apis(RequestHandlerSelectors.basePackage("com.gblfy.springbootswagger2")).paths(PathSelectors.any()).build().apiInfo(new ApiInfoBuilder()//標(biāo)題.title("SpringBoot2.x整合Swagger2 構(gòu)建api文檔")//簡介.description("簡單優(yōu)雅的restfun風(fēng)格，詳細(xì)信息......")//版本.version("9.0")//作者個人信息.contact(new Contact("技術(shù)論壇", "https://gblfy.com", "gblfy@gmail.com")).license("The Apache License")//服務(wù)條款.licenseUrl("https://gblfy.com").build());} }

這里提供一個配置類，首先通過@EnableSwagger2注解啟用Swagger2，然后配置一個Docket Bean，這個Bean中，配置映射路徑和要掃描的接口的位置，在apiInfo中，主要配置一下Swagger2文檔網(wǎng)站的信息，例如網(wǎng)站的title，網(wǎng)站的描述，聯(lián)系人的信息，使用的協(xié)議等等。

如此，Swagger2就算配置成功了，非常方便。

此時啟動項目，輸入http://localhost:8080/swagger-ui.html，能夠看到如下頁面，說明已經(jīng)配置成功了：

三、創(chuàng)建接口

接下來就是創(chuàng)建接口了，Swagger2相關(guān)的注解其實并不多，而且很容易懂，下面我來分別向小伙伴們舉例說明：

package com.gblfy.springbootswagger2.controller;import com.gblfy.springbootswagger2.entity.User; import io.swagger.annotations.Api; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiImplicitParams; import io.swagger.annotations.ApiOperation; import org.springframework.web.bind.annotation.*;import java.util.*;/*** @author gblfy* @ClassNme UserController* @Description 用戶管理接口* @Date 2019/11/5 20:26* @version 1.0*/ @Api(tags = "用戶管理相關(guān)接口") @RestController @RequestMapping(value = "/user") public class UserController {// 創(chuàng)建線程安全的Map 用戶封裝用戶數(shù)據(jù)public static Map<Long, User> userList = Collections.synchronizedMap(new HashMap<Long, User>());/*** 獲取用戶列表 封裝公用** @return*/@ApiOperation(value = "獲取用戶列表", notes = "這里填寫接口方法描述")@GetMapping("/list")public List<User> getUserList() {// 處理"/userList/"的GET請求，用來獲取用戶列表// 還可以通過@RequestParam從頁面中傳遞參數(shù)來進(jìn)行查詢條件或者翻頁信息的傳遞List<User> users = new ArrayList<User>(userList.values());return users;}/*** 創(chuàng)建用戶** @param user* @return*/@ApiOperation(value = "創(chuàng)建用戶", notes = "根據(jù)User對象創(chuàng)建用戶")@ApiImplicitParam(name = "user", value = "用戶詳細(xì)實體user", required = true, dataType = "User")@PostMapping("/")public String postUser(@RequestBody User user) {// 處理"/userList/"的POST請求，用來創(chuàng)建User// 除了@ModelAttribute綁定參數(shù)之外，還可以通過@RequestParam從頁面中傳遞參數(shù)userList.put(user.getId(), user);return "success";}/*** 根據(jù)用戶id,獲取用戶詳細(xì)信息** @param id* @return*/@ApiOperation(value = "獲取用戶詳細(xì)信息", notes = "根據(jù)url的id來獲取用戶詳細(xì)信息")@ApiImplicitParam(name = "id", value = "用戶ID", required = true, dataType = "Long")@GetMapping(value = "/{id}")public User getUser(@PathVariable Long id) {// 處理"/userList/{id}"的GET請求，用來獲取url中id值的User信息// url中的id可通過@PathVariable綁定到函數(shù)的參數(shù)中return userList.get(id);}/*** 根據(jù)用戶id,更新用戶詳細(xì)信息** @param id* @param user* @return*/@ApiOperation(value = "更新用戶詳細(xì)信息", notes = "根據(jù)url的id來指定更新對象，并根據(jù)傳過來的user信息來更新用戶詳細(xì)信息")@ApiImplicitParams({@ApiImplicitParam(name = "id", value = "用戶ID", required = true, dataType = "Long"),@ApiImplicitParam(name = "user", value = "用戶詳細(xì)實體user", required = true, dataType = "User")})@PutMapping(value = "/{id}")public String putUser(@PathVariable Long id, @ModelAttribute User user) {// 處理"/userList/{id}"的PUT請求，用來更新User信息User u = userList.get(id);u.setUserName(user.getUserName());u.setAge(user.getAge());userList.put(id, u);return "success";}/*** 根據(jù)用戶id,刪除用戶信息** @param id* @return*/@ApiOperation(value = "刪除用戶", notes = "根據(jù)url的id來指定刪除對象")@ApiImplicitParam(name = "id", value = "用戶ID", required = true, dataType = "Long")@DeleteMapping(value = "/{id}")public String deleteUser(@PathVariable Long id) {// 處理"/userList/{id}"的DELETE請求，用來刪除UseruserList.remove(id);return "success";} }

四、創(chuàng)建實體類

package com.gblfy.springbootswagger2.entity;import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import lombok.AllArgsConstructor; import lombok.Builder; import lombok.Data; import lombok.NoArgsConstructor;/*** @author gblfy* @ClassNme User* @Description TODO* @Date 2019/11/5 20:31* @version1.0*/ @ApiModel @Data @AllArgsConstructor @NoArgsConstructor @Builder public class User {@ApiModelProperty(value = "用戶id")private long id;@ApiModelProperty(value = "用戶名")private String userName;@ApiModelProperty(value = "用戶年齡")private Integer age; }

五、Swagger2 APL介紹

注解說明

@Api	用來標(biāo)記當(dāng)前Controller的功能
@ApiOperation	用來標(biāo)記一個方法的作用
@ApiImplicitParam	用來描述一個參數(shù)，可以配置參數(shù)的中文含義，也可以給參數(shù)設(shè)置默認(rèn)值，這樣在接口測試的時候可以避免手動輸入，@ApiImplicitParam注解中雖然可以指定參數(shù)是必填的，但是卻不能代替
@ApiImplicitParams	如果有多個參數(shù)，則需要使用多個@ApiImplicitParam注解來描述，多個@ApiImplicitParam注解需要放在一個@ApiImplicitParams注解中
@RequestParam(required = true)	，前者的必填只是在Swagger2框架內(nèi)必填，拋棄了Swagger2，這個限制就沒用了，所以假如開發(fā)者需要指定一個參數(shù)必填，@RequestParam(required = true)注解還是不能省略
@ApiModel	如果參數(shù)是一個對象（例如上文的更新接口），對于參數(shù)的描述也可以放在實體類中
@ApiModelProperty	用戶成員變量中

六、頁面效果

七、API驗證測試

操作：技巧 2步走
【Try it out】-【Execute】

7.1. 獲取用戶列表接口

用戶信息為空

7.2. 創(chuàng)建用戶

添加用戶成功
在調(diào)用一次，查詢用戶列表接口

7.3. 根據(jù)用戶id,獲取用戶詳細(xì)信息

7.4. 根據(jù)用戶id,更新用戶詳細(xì)信息

更新用戶信息后，再次調(diào)用獲取用戶列表接口

7.5. 根據(jù)用戶id,刪除用戶信息

刪除用戶信息后，再次調(diào)用獲取用戶列表接口

總結(jié)

以上是生活随笔為你收集整理的SpringBoot2.x整合Swagger2 实现API文档实时生成的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。