前后端分離之Swagger2

1. 問題描述

隨着軟件過程的不斷發展，前后端分離開發模式被越來越的開發團隊使用，今天介紹下前后分離中必用的接口設計與調試工具-swagger2，前端人員根據swagger的描述，進行參數的傳遞；前后端聯調的時候，出現問題，首先使用swagger進行測試調用，定位問題，還可以通過界面導出swagger2接口文檔，修改完善后作為其他系統調用說明文檔。

2. 問題方案

采用springboo+swagger2方式運行swagger。

2.1 pom文件配置

        <!--swagger-->
        <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>

2.2 springboot啟動類配置標簽

@EnableSwagger2             //啟動swagger注解
@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

2.3 java代碼及swagger界面說明

2.3.1 java代碼（針對實際項目做了下處理）

@Api(description = "測試管理類")
public class TestController {

 @RequestMapping(value = "/getTestByUid", method = RequestMethod.GET)
    @ApiOperation(value = "查詢接口,獲取當前用戶數據", response = Object.class)
    public Object getTestByUid(@ApiParam(value = "類型，1公開，2新建，3收藏4，分享") @RequestParam String type) {
        try {
            Object result = testService.getTestByUid(type);
            return new ResponseEntity(result, HttpStatus.OK);
        } catch (Exception e) {
            logger.error("查詢接口報錯", e);
            return new ResponseEntity(e.getMessage(), HttpStatus.INTERNAL_SERVER_ERROR);
        }
    }
    }

2.3.2 swagger效果圖

2.3.3 swagger界面說明

一般使用這幾個標簽就夠用了，詳細API說明可以百度一下，就不一一說明了。

（1） @Api(description = "測試管理類")

​ 該標簽用於類上，是對整個類的說明，例如：用戶管理模塊，會在swagger2界面上生成一個一級菜單，方法是它的二級菜單。

（2） @ApiOperation(value = "查詢接口,獲取當前用戶數據", response = Object.class)

該標簽用於方法上，Value是描述，還可以定義nodes進行進一步說明。

（3）@ApiParam(value = "類型，1公開，2新建，3收藏4，分享")

改標簽用於定義參數描述。

三個標簽分別是類->方法->參數

另外：點擊 ”Try it out“按鈕就可以調用后台服務，進行前后端聯調測試及問題定位。

---