采用swagger ui可實現接口可視化，脫離寫接口文檔的痛苦，及避免不厭其煩地解說各接口需要的參數和返回結果
一、什么是swagger
Swagger的目標是為REST APIs 定義一個標准的，與語言無關的接口，使人和計算機在看不到源碼或者看不到文檔或者不能通過網絡流量檢測的情況下能發現和理解各種服務的功能。當服務通過Swagger定義，消費者就能與遠程的服務互動通過少量的實現邏輯。類似於低級編程接口，Swagger去掉了調用服務時的很多猜測。
二、swagger的優勢
1.整體文檔界面清晰易看
使用swagger生成的接口文檔直觀可視，脫離寫接口文檔的痛苦，及避免不厭其煩地解說各接口需要的參數和返回結果
2. 接口文檔的查看簡單易懂
接口路徑查看
需要傳遞的參數查看
調用成功后返回的json數據有什么參數，參數的意思的什么的查看
3. 接口測試便利
接口測試，只需填好傳參，然后點擊Try it out！按鈕即可
三、Swagger整合springMVC
1.依賴管理
| <!-- swagger-springmvc --> <dependency> <groupId>com.mangofactory</groupId> <artifactId>swagger-springmvc</artifactId> <version>1.0.2</version> </dependency> <dependency> <groupId>com.mangofactory</groupId> <artifactId>swagger-models</artifactId> <version>1.0.2</version> </dependency> <dependency> <groupId>com.wordnik</groupId> <artifactId>swagger-annotations</artifactId> <version>1.3.11</version> </dependency> <!-- swagger-springmvc dependencies --> <dependency> <groupId>com.google.guava</groupId> <artifactId>guava</artifactId> <version>15.0</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-annotations</artifactId> <version>2.4.4</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version>2.4.4</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-core</artifactId> <version>2.4.4</version> </dependency> <dependency> <groupId>com.fasterxml</groupId> <artifactId>classmate</artifactId> <version>1.1.0</version> </dependency> |
2. Swagger配置
Swagger的配置實際上就是自定義一個Config類，通過java編碼的方式實現配置。代碼如下：
| @Configuration @EnableSwagger public class SwaggerConfig {
private SpringSwaggerConfig springSwaggerConfig;
@Autowired public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) { this.springSwaggerConfig = springSwaggerConfig; }
/* * Spring在啟動的時候檢測到@Bean的時候默認會在容器中注入一個以方法名（你的代碼中是user）命名的Bean，而這個Bean用的是和該方法的返回類型一樣的類（你的代碼中是User）來初始化的。 */ @Bean public SwaggerSpringMvcPlugin customImplementation(){ return new SwaggerSpringMvcPlugin(this.springSwaggerConfig) .apiInfo(apiInfo()) .enable(ConfigUtil.getInstance().getBoolean("enableSwagger"))//用於控制設置使用swagger .includePatterns(".*?"); }
private ApiInfo apiInfo(){ return new ApiInfo(ConfigUtil.getInstance().get("project.name"),"接口文檔",null,ConfigUtil.getInstance().get("email"),null,null); }
} |
其中配置文件信息
| #swagger 參數信息 enableSwagger=true project.name=swagger email=swagger@163.com |
然后，將該配置交給spring管理，在springmvc的配置文件中加入以下配置
| <bean class="ssm.configer.SwaggerConfig "/> |
或可通過掃描注入
自定義操作對象的接口方法
| @Api(value="test-doc",description="用於測試") @Controller @RequestMapping("/test") public class TestController {
@Autowired private CustomerService customerService;
@RequestMapping(value="/get", method = RequestMethod.GET) @ApiOperation(value="根據用戶名獲取對象",notes="獲取對象") public @ResponseBody CustomResult get( @ApiParam("電話號碼，必選") @RequestParam(value="phone",required=true)String phone) { //Customer customer = customerService.findByPhone(phone); Customer customer = new Customer(); customer.setName("he"); return CustomResult.ok(customer); }
@RequestMapping(value="/find", method = RequestMethod.POST) @ApiOperation(value="根據用戶名獲取對象",notes="獲取對象") @ApiResponses({ @ApiResponse(code=Constance.BASE_SUCCESS_CODE,message="成功",response=Customer.class), @ApiResponse(code=Constance.BASE_FAIL_CODE,message="失敗",response=String.class) }) public @ResponseBody CustomResult find( @ApiParam("電話號碼，必選") @RequestParam(value="phone",required=true)String phone) { //Customer customer = customerService.findByPhone(phone); Customer customer; try { customer = new Customer(); customer.setName("he"); } catch (Exception e) { // TODO Auto-generated catch block e.printStackTrace(); return CustomResult.build(Constance.BASE_FAIL_CODE, Constance.map.get(Constance.BASE_FAIL_CODE)); } return CustomResult.ok(customer); } } |
3. Swagger ui配置
從https://github.com/swagger-api/swagger-ui 獲取其所有的 dist 目錄下東西放到需要集成的項目里，本文放入 WebRoot/static/swagger/ 目錄下。
修改swagger/index.html文件，並將其放在WebRoot下，如下
因為swagger-ui項目都是靜態資源，restful形式的攔截方法會將靜態資源進行攔截處理，所以在springmvc配置文件中需要配置對靜態文件的處理方式。
| <mvc:default-servlet-handler></mvc:default-servlet-handler> |
打開瀏覽器直接訪問項目下的index.html文件，即可看到接口文檔說明了
四、Swagger的使用
整合好項目
然后就放進tomcat，啟動
路徑通常是:項目名+/api.html
這個就是寫好的api，分別對應是以下這樣
填好要傳的參數，然后try it out按鈕就能進行接口測試
客戶端返回狀態碼
然后在Api接口添加這些
下面就是實體類的參數中文說明
