swagger:超好用的接口API工具,對於後臺來說不需要專門寫測試頁面就可以對接口進行調試。
使用swagger 步驟
第一步:引入所需jar包
<!-- swagger -->
<dependency>
<groupId>com.mangofactory</groupId>
<artifactId>swagger-springmvc</artifactId>
<version>1.0.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.7.5</version>
</dependency>
第二步:自定義相關配置
package com.test.document;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.mvc.method.RequestMappingInfoHandlerMapping;
import org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2 //Loads the spring beans required by the framework
public class MySwaggerConfig {
@Bean
public Docket userApi() {
return new Docket(DocumentationType.SWAGGER_2)
.select() // 選擇那些路徑和api會生成document
.apis(RequestHandlerSelectors.any()) // 對所有api進行監控
.paths(PathSelectors.any()) // 對所有路徑進行監控
.build();
}
@Bean
public RequestMappingInfoHandlerMapping requestMapping(){
return new RequestMappingHandlerMapping();
}
}
第三步:在applicationContext.xml文件中進行配置
<!-- 引入swagger相關 -->
<bean class="com.test.document.MySwaggerConfig"/>
<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/" />
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/" />
第四步:在springMVC配置文件中引入swagger相關配置
<bean class="springfox.documentation.swagger2.configuration.Swagger2DocumentationConfiguration" id="swagger2Config"/>
第五步:在controller層配置controller和方法
package com.test.controller;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;
import com.wordnik.swagger.annotations.ApiOperation;
import io.swagger.annotations.Api;
@Controller
@RequestMapping(value="/TestExcelFast")
@Api(value = "restful", description = "測試")
public class TestExcelFastController {
@ApiOperation(value = "測試swagger")
@RequestMapping(value="/test",method=RequestMethod.GET)
@ResponseBody
public String test(){
String str = "123";
System.out.println(1);
return str;
}
}
第六步:啓動項目訪問swagger
http://localhost:8080/項目名稱/swagger-ui.htm
swagger註解說明
@Api:用在請求的類上,表示對類的說明
tags="說明該類的作用,可以在UI界面上看到的註解"
value="該參數沒什麼意義,在UI界面上也看到,所以不需要配置"
@ApiOperation:用在請求的方法上,說明方法的用途、作用
value="說明方法的用途、作用"
notes="方法的備註說明"
@ApiImplicitParams:用在請求的方法上,表示一組參數說明
@ApiImplicitParam:用在@ApiImplicitParams註解中,指定一個請求參數的各個方面
name:參數名
value:參數的漢字說明、解釋
required:參數是否必須傳
paramType:參數放在哪個地方
· header --> 請求參數的獲取:@RequestHeader
· query --> 請求參數的獲取:@RequestParam
· path(用於restful接口)--> 請求參數的獲取:@PathVariable
· body(不常用)
· form(不常用)
dataType:參數類型,默認String,其它值dataType="Integer"
defaultValue:參數的默認值
@ApiResponses:用在請求的方法上,表示一組響應
@ApiResponse:用在@ApiResponses中,一般用於表達一個錯誤的響應信息
code:數字,例如400
message:信息,例如"請求參數沒填好"
response:拋出異常的類
@ApiModel:用於響應類上,表示一個返回響應數據的信息
(這種一般用在post創建的時候,使用@RequestBody這樣的場景,
請求參數無法使用@ApiImplicitParam註解進行描述的時候)
@ApiModelProperty:用在屬性上,描述響應類的屬性
1.@Api:用在請求的類上,說明該類的作用
@Api:用在請求的類上,說明該類的作用
tags="說明該類的作用"
value="該參數沒什麼意義,所以不需要配置"
示例:@Api(tags="APP用戶註冊Controller")
2.@ApiOperation:用在請求的方法上,說明方法的作用
@ApiOperation:"用在請求的方法上,說明方法的作用"
value="說明方法的作用"
notes="方法的備註說明"
示例:@ApiOperation(value="用戶註冊",notes="手機號、密碼都是必輸項,年齡隨邊填,但必須是數字")
3.@ApiImplicitParams:用在請求的方法上,包含一組參數說明
@ApiImplicitParams:用在請求的方法上,包含一組參數說明
@ApiImplicitParam:用在 @ApiImplicitParams 註解中,指定一個請求參數的配置信息
name:參數名
value:參數的漢字說明、解釋
required:參數是否必須傳
paramType:參數放在哪個地方
· header --> 請求參數的獲取:@RequestHeader
· query --> 請求參數的獲取:@RequestParam
· path(用於restful接口)--> 請求參數的獲取:@PathVariable
· body(不常用)
· form(不常用)
dataType:參數類型,默認String,其它值dataType="Integer"
defaultValue:參數的默認值
示例:@ApiImplicitParams({
@ApiImplicitParam(name="mobile",value="手機號",required=true,paramType="form"),
@ApiImplicitParam(name="password",value="密碼",required=true,paramType="form"),
@ApiImplicitParam(name="age",value="年齡",required=true,paramType="form",dataType="Integer")
})
4.@ApiResponses:用於請求的方法上,表示一組響應
@ApiResponses:用於請求的方法上,表示一組響應
@ApiResponse:用在@ApiResponses中,一般用於表達一個錯誤的響應信息
code:數字,例如400
message:信息,例如"請求參數沒填好"
response:拋出異常的類
示例:@ApiOperation(value = "select1請求",notes = "多個參數,多種的查詢參數類型")
@ApiResponses({
@ApiResponse(code=400,message="請求參數沒填好"),
@ApiResponse(code=404,message="請求路徑沒有或頁面跳轉路徑不對")
})
5.@ApiModel:用於響應類上,表示一個返回響應數據的信息
@ApiModel:用於響應類上,表示一個返回響應數據的信息
(這種一般用在post創建的時候,使用@RequestBody這樣的場景,
請求參數無法使用@ApiImplicitParam註解進行描述的時候)
@ApiModelProperty:用在屬性上,描述響應類的屬性
示例:
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import java.io.Serializable;
@ApiModel(description= "返回響應數據")
public class RestMessage implements Serializable{
@ApiModelProperty(value = "是否成功")
private boolean success=true;
@ApiModelProperty(value = "返回對象")
private Object data;
@ApiModelProperty(value = "錯誤編號")
private Integer errCode;
@ApiModelProperty(value = "錯誤信息")
private String message;
/* getter/setter */
}