詳解spring cloud整合Swagger2構(gòu)建RESTful服務(wù)的APIs

2024-07-13 10:17:16

字體：大中小

供稿：網(wǎng)友

前言

在前面的博客中，我們將服務(wù)注冊到了Eureka上，可以從Eureka的UI界面中，看到有哪些服務(wù)已經(jīng)注冊到了Eureka Server上，但是，如果我們想查看當(dāng)前服務(wù)提供了哪些RESTful接口方法的話，就無從獲取了，傳統(tǒng)的方法是梳理一篇服務(wù)的接口文檔來供開發(fā)人員之間來進(jìn)行交流，這種情況下，很多時(shí)候，會(huì)造成文檔和代碼的不一致性，比如說代碼改了，但是接口文檔沒有改等問題，而Swagger2則給我們提供了一套完美的解決方案，下面，我們來看看Swagger2是如何來解決問題的。

一、引入Swagger2依賴的jar包

<!-- swagger2 -->     <dependency>       <groupId>io.springfox</groupId>       <artifactId>springfox-swagger2</artifactId>       <version>2.2.2</version>     </dependency>     <dependency>       <groupId>io.springfox</groupId>       <artifactId>springfox-swagger-ui</artifactId>       <version>2.2.2</version>     </dependency>

二、初始化Swagger2的配置

@Configuration @EnableSwagger2 // 啟用Swagger2 public class Swagger2 {    @Bean   public Docket createRestApi() {// 創(chuàng)建API基本信息     return new Docket(DocumentationType.SWAGGER_2)         .apiInfo(apiInfo())         .select()         .apis(RequestHandlerSelectors.basePackage("com.chhliu.jpa"))// 掃描該包下的所有需要在Swagger中展示的API，@ApiIgnore注解標(biāo)注的除外         .paths(PathSelectors.any())         .build();   }    private ApiInfo apiInfo() {// 創(chuàng)建API的基本信息，這些信息會(huì)在Swagger UI中進(jìn)行顯示     return new ApiInfoBuilder()         .title("Spring Boot中使用Swagger2構(gòu)建RESTful APIs")// API 標(biāo)題         .description("rdcloud-jpa提供的RESTful APIs")// API描述         .contact("chhliu@")// 聯(lián)系人         .version("1.0")// 版本號(hào)         .build();   }  }

注：該配置類需要在Application同級(jí)目錄下創(chuàng)建，在項(xiàng)目啟動(dòng)的時(shí)候，就初始化該配置類

三、完善API文檔信息

public interface SonarControllerI {   @ApiOperation(value="獲取項(xiàng)目組Sonar對(duì)應(yīng)的Url信息", notes="根據(jù)id獲取項(xiàng)目組Sonar對(duì)應(yīng)的Url信息")// 使用該注解描述接口方法信息   @ApiImplicitParams({       @ApiImplicitParam(name = "id", value = "SonarUrl表ID", required = true, dataType = "Long", paramType="path")   })// 使用該注解描述方法參數(shù)信息，此處需要注意的是paramType參數(shù)，需要配置成path，否則在UI中訪問接口方法時(shí)，會(huì)報(bào)錯(cuò)   @GetMapping("/get/{id}")   SonarUrl get(@PathVariable Long id);      @ApiOperation(value="獲取項(xiàng)目組Sonar對(duì)應(yīng)的所有Url信息")   @GetMapping("/get/all")   List<SonarUrl> getAll(); }

注：paramType表示參數(shù)的類型，可選的值為"path","body","query","header","form"

四、完善返回類型信息

@Entity(name = "SONAR_URL") public class SonarUrl implements Serializable {    /**    *    */   private static final long serialVersionUID = 1L;   @ApiModelProperty(value="主鍵", hidden=false, notes="主鍵，隱藏", required=true, dataType="Long")// 使用該注解描述屬性信息,當(dāng)hidden=true時(shí)，該屬性不會(huì)在api中顯示   @Id   @GeneratedValue(strategy = GenerationType.AUTO)   private Long id;      @ApiModelProperty(value="URL鏈接地址")   @Column(name="URL")   private String url;      @ApiModelProperty(value="項(xiàng)目組")   @Column(name="TEAM")   private String team;    @ApiModelProperty(value="部門")   @Column(name="DEPARTMENT")   private String department;     ……省略getter，setter方法……  }

五、啟動(dòng)應(yīng)用

1、在瀏覽器中輸入：http://localhost:7622/swagger-ui.html

2、結(jié)果如下：

spring,cloud,構(gòu)建,cloud整合Swagger2,APIs