支付系統 - Swagger 的快樂你不懂[減壓文]

前言

這篇文章聊一點放鬆的內容（反正我以爲挺放鬆挺解壓的，水完這篇文章之後，我準備睡個好覺）

常常和前端聯調的時候，須要提供文檔（就很煩）。若是是本身新寫的接口還好，怕就怕是以前的老接口，各類返回值的邏輯都不太清楚了，找原來的文檔又找不到，找到了還必定是最新的。此時，我就在想能不能搞個東西讓它自動生成文檔。解決一下這個文檔不跟着代碼走的老大難問題。

好在是，優秀的人老是不謀而合，我隨便搜了一下就找到了Swagger。雖然頁面有點醜，可是無傷大雅。畢竟我是一個有內涵的人，外表什麼的關了燈都同樣（非開車）。因此這裏我就從零記錄了怎麼在SpringBooot搭建的Web工程中使用這個工具。

由於是第一次摸索，不免有用的姿式不太正確的地方，確定不是最佳實踐。嚴格來說不是一篇教程性質的文章，我稱它爲減壓文，若是有讀者看見了以爲我誤導了他，有本事你來打我啊。

正文

簡介

既然是工具的使用，就作個簡單的自我介紹。我，Swagger是基於Java註解生成在線文檔的一個框架，個人原理很是的簡單。做爲一個工具人，大家只要關注如何用好用出最高水平就好了。

Springboot 集成 Swagger

打開你的POM，引入下面的依賴。沒有POM？請點擊右上角的關閉按鈕，相信你的心情也會好起來。

<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> 複製代碼

另外，須要自動激活配置，通常是在基於annotation的Spring配置類中加入@EnableSwagger2註解。沒有基於註解的配置類？請點擊右上角的關閉按鈕，相信你的心情也會好起來。

@EnableSwagger2
@Configuration public class PayOpenApiConfiguration{   @Bean  public Docket customDocket() {  return new Docket(DocumentationType.SWAGGER_2)  .apiInfo(apiInfo())  .select()  .apis(RequestHandlerSelectors.any())  .paths(PathSelectors.any())  .build();  }   private ApiInfo apiInfo() {  Contact contact = new Contact("pleuvoir", "https://github.com/pleuvoir/compose-pay", "pleuvoir@foxmail.com");  return new ApiInfoBuilder()  .title("支付系統開放API")  .description("支付系統開放API")  .contact(contact)  .version("1.0.0")  .build();  } } 複製代碼

還須要定義Docket對象，用來配置一些生效參數。其中RequestHandlerSelectors.any()配置的是Swagger包掃描的範圍，你也能夠配置爲RequestHandlerSelectors.basePackage("io.github.pleuvoir")工程中指定的包。我最後配置的包，由於用any它給我搞了一些Error相關的東西出來，誰讓你出來的，給我回去。

apiInfo配置的內容包含標題，描述，版本，聯繫人等信息。相信聰明的你一看就知道，至於裏面還有什麼其餘的配置點進去看看便知，我不想再這叨叨了。

有了這些配置框架層面的配置工做就完成了，接下里進入到萬衆期待的api聲明環節。什麼，你不期待？分手吧，咱們不是一路人。請點擊右上角的關閉按鈕，相信你的心情也會好起來。

Swagger 接口配置示例

文章開頭提到了，這是一項使用註解來生成文檔的工具。那咱們來看看都有哪些註解吧。爲了方便圍觀，我將它們列在了表格中。

註解	做用域
@Api	類上
@ApiOperation	方法上
@ApiParam	方法的入參
@ApiImplicitParam	方法的入參
@ApiImplicitParams	方法的入參
@ApiModel	實體類
@ApiModelProperty	實體類中的屬性
@ApiIgnore	類/方法/方法入參

說了你可能不信，就這麼幾個註解，還有這些做用域，我看着就感受怪煩的，另外這些做用域還整理的時候還可能搞錯了。到最後我也就只用到了@ApiOperation @ApiModel @ApiModelProperty，不信你本身往下看。

說一千道一萬，不如看代碼來的實在：

@ApiOperation(value = "發紅包", notes = "建立紅包活動", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
@RequestMapping(value = "createActivity", method = RequestMethod.POST) public ResultMessageDTO<CreateActivityResultDTO> createActivity(@ApiParam @RequestBody CreateActivityDTO createActivityDTO) {  ResultMessageDTO data = new ResultMessageDTO();  data.setData(System.currentTimeMillis());  return data; }  @ApiModel("建立紅包活動返回實體類") public class CreateActivityDTO implements ToJSON {   @ApiModelProperty("總金額")  private BigDecimal totalAmount;   @ApiModelProperty("用戶編號")  private Long userId;   @ApiModelProperty("紅包總數")  private Integer total;  }  @ApiModel("建立紅包活動返回結果實體類") public class CreateActivityResultDTO {   @ApiModelProperty("活動id")  private Long activityId; } 複製代碼

別人的教程都說要在Controller的類上加@Api註解，我試了不加也沒事，我就不加了。我是一個簡單質樸的人，我喜歡簡單，簡單就是美，我但願我愛的人也是一個簡單的人。

配置完成後根據你項目的請求地址訪問自帶的頁面，我這裏是http://127.0.0.1:8081/swagger-ui.html，能夠看到一個綠汪汪的頁面彈了出來。固然了，我這裏只是示例，支付系統的相關接口尚未實現，因此就拿其它的濫竽充數。

swagger-ui

對了，當我點擊了發紅包的按鈕後發現了一件事情：

竟然有個按鈕讓我Try一Try，這我不能忍啊，我就試着踹了一下，沒想到索然無味之中發現了新的快樂。

這個東西有點意思，能夠直接請求到後臺，是否是之後能夠偷懶不用Postwomen了，想到這裏我有點小激動。

看到這個返回值我不由感慨，科技從業者的快樂就是這麼簡單。很久沒口吐芬芳了，雖然不知道罵了誰，可是好減壓啊！今天我只想安安靜靜的作一個祖安男孩。

可能遇到的問題

與 guava 版本衝突

根據報錯的提示，寧肯能須要排掉一個版本，至於排哪一個你本身去試。

找不到頁面

訪問/swagger-ui.html找不到頁面，緣由是Swagger的頁面是打在JAR中的。

swagger-ui

解決方法：若是是在Springboot中，在實現WebMvcConfigurer的配置類中增長以下代碼：

@Override
 public void addResourceHandlers(ResourceHandlerRegistry registry) {  registry.addResourceHandler("swagger-ui.html")  .addResourceLocations("classpath:/META-INF/resources/");  registry.addResourceHandler("/webjars/**")  .addResourceLocations("classpath:/META-INF/resources/webjars/");  } 複製代碼

而後再訪問就能夠了。若是沒好，你本身再查查，我也不會。

資源集散地

百度一下，你就知道

後語

我沒什麼想說的，祝你們身體健康，萬事如意，看完這篇文章後又年輕了五歲。沒有人永遠十八歲，但年年有人十八歲。晚安，美夢。