SpringBoot開發案例之整合Swagger篇

  • 2019 年 12 月 5 日
  • 筆記

前段時間整合過的一個支付服務，由於使用了Spring Boot快速開發，但是又懶得寫詳細的文檔介紹，便順手就把Swagger整合進來了，對支付服務進行分組API展示，如上圖。

簡介

Swagger 是一個規範和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。總體目標是使客戶端和文件系統作為伺服器以同樣的速度來更新 。介面的方法，參數和模型緊密集成到伺服器端的程式碼，允許API來始終保持同步。Swagger 讓部署管理和使用功能強大的API從未如此簡單。

在實際開發過程中，我們的RESTful API就有可能要面對多個開發人員或多個開發團隊：IOS開發、Android開發、Web開發等。為了減少與其他團隊平時開發期間的頻繁溝通成本，傳統做法我們會創建一份RESTful API文檔來記錄所有介面細節，然而這樣的做法有以下幾個問題：

  • 由於介面眾多，並且細節複雜（需要考慮不同的HTTP請求類型、HTTP頭部資訊、HTTP請求內容等），高品質地創建這份文檔本身就是件非常吃力的事，下游的抱怨聲不絕於耳
  • 隨著時間推移，不斷修改介面實現的時候都必須同步修改介面文檔，而文檔與程式碼又處於兩個不同的媒介，除非有嚴格的管理機制，不然很容易導致不一致現象

而swagger完美的解決了上面的幾個問題，並與Spring boot程式配合組織出強大RESTful API文檔。它既可以減少我們創建文檔的工作量，同時說明內容又整合入實現程式碼中，讓維護文檔和修改程式碼整合為一體，可以讓我們在修改程式碼邏輯的同時方便的修改文檔說明。另外Swagger2也提供了強大的頁面測試功能 來調試每個RESTful API。

添加Swagger2依賴

<!-- swagger2 文檔 截止目前 為最新版本 -->  <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>

創建Swagger2配置類

在Application.java同級包下創建Swagger2的配置類。

@Configuration //讓Spring來載入該類配置  @EnableSwagger2 //啟用Swagger2  public class Swagger2 {      @Bean      public Docket alipayApi() {          return new Docket(DocumentationType.SWAGGER_2)                  .groupName("支付寶API介面文檔")                  .apiInfo(apiInfo())                  .select()                  .apis(RequestHandlerSelectors.basePackage("com.itstyle.modules.alipay"))                  .paths(PathSelectors.any()).build();      }      @Bean      public Docket weixinpayApi() {          return new Docket(DocumentationType.SWAGGER_2)                  .groupName("微信API介面文檔")                  .apiInfo(apiInfo())                  .select()                  .apis(RequestHandlerSelectors.basePackage("com.itstyle.modules.weixinpay"))                  .paths(PathSelectors.any()).build();      }      @Bean      public Docket unionpayApi() {          return new Docket(DocumentationType.SWAGGER_2)                  .groupName("銀聯API介面文檔")                  .apiInfo(apiInfo())                  .select()                  .apis(RequestHandlerSelectors.basePackage("com.itstyle.modules.unionpay"))                  .paths(PathSelectors.any()).build();      }      private ApiInfo apiInfo() {          return new ApiInfoBuilder()                  .title("支付系統")                  .description("微信、支付寶、銀聯支付服務")                  .termsOfServiceUrl("http://blog.52itstyle.com")                  .contact(new Contact("科幫網 ", "http://blog.52itstyle.com", "[email protected]"))                  .version("1.0").build();      }    }

添加API註解

API說明：

/**    swagger2使用說明：           @Api：用在類上，說明該類的作用           @ApiOperation：用在方法上，說明方法的作用           @ApiIgnore：使用該註解忽略這個API           @ApiImplicitParams：用在方法上包含一組參數說明           @ApiImplicitParam：用在@ApiImplicitParams註解中，指定一個請求參數的各個方面              paramType：參數放在哪個地方                   header-->請求參數的獲取：@RequestHeader                   query-->請求參數的獲取：@RequestParam                   path（用於restful介面）-->請求參數的獲取：@PathVariable                   body（不常用）                   form（不常用）               name：參數名               dataType：參數類型               required：參數是否必須傳               value：參數的意思               defaultValue：參數的默認值           @ApiResponses：用於表示一組響應           @ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應資訊               code：數字，例如400               message：資訊，例如"請求參數沒填好"               response：拋出異常的類           @ApiModel：描述一個Model的資訊（這種一般用在post創建的時候，使用@RequestBody這樣的場景，請求參數無法使用@ApiImplicitParam註解進行描述的時候）              @ApiModelProperty：描述一個model的屬性   */

程式碼實現：

/**   * 銀聯支付   * 創建者 科幫網   * 創建時間    2017年8月2日   */  @Api(tags ="銀聯支付")  @Controller  @RequestMapping(value = "unionpay")  public class UnionPayController {      private static final Logger logger =    LoggerFactory.getLogger(AliPayController.class);        @Autowired      private IUnionPayService unionPayService;    @ApiOperation(value="銀聯支付主頁")   @RequestMapping(value="index",method=RequestMethod.GET)      public String   index() {          return "unionpay/index";      }    @ApiOperation(value="電腦支付")  @RequestMapping(value="pcPay",method=RequestMethod.POST)  @ApiImplicitParam(name = "product", value = "產品資訊", required = true, dataType = "Product")     public String  pcPay(Product product,ModelMap map) {          logger.info("電腦支付");          product.setPayWay(PayWay.PC.getCode());          String form  =  unionPayService.unionPay(product);          map.addAttribute("form", form);          return "unionpay/pay";      }  @ApiIgnore//使用該註解忽略這個API  @ApiOperation(value="手機H5支付")  @RequestMapping(value="mobilePay",method=RequestMethod.POST)      public String  mobilePay(Product product,ModelMap map) {          logger.info("手機H5支付");          product.setPayWay(PayWay.MOBILE.getCode());          String form  =  unionPayService.unionPay(product);          map.addAttribute("form", form);          return "unionpay/pay";      }  }

訪問

配置完成後，我們重啟服務，訪問地址 http://localhost:8080/項目名/swagger-ui.html，如：

http://localhost:8080/springboot_pay/swagger-ui.html

Tags:

VirMach 便宜 VPS