58
SpringBoot開發案例之整合Swagger篇
前段時間整合過的一個支付服務，由於使用了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("https://blog.52itstyle.com")
.contact(new Contact("科幫網 ", "https://blog.52itstyle.com", "345849402@qq.com"))
.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";
}
}
訪問
配置完成後，我們重啟服務，訪問地址 https://localhost:8080/項目名/swagger-ui.html，如：
https://localhost:8080/springboot_pay/swagger-ui.html
完整項目案例可查看 支付服務。
作者： 小柒
出處： https://blog.52itstyle.com
分享是快樂的，也見證了個人成長曆程，文章大多都是工作經驗總結以及平時學習積累，基於自身認知不足之處在所難免，也請大家指正，共同進步。
最後更新：2017-08-29 13:32:29