純手打……
前後端分離模式下，簡化對接，提交效率
對於後端開發人員，使用swagger維護在線接口文檔
spring集成了swagger，形成Spring-swagger項目
實際使用：
1：引入依賴：
<!-- swagger核心組件，在代碼配置swagger時會依賴到它 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- swagger的用戶界面，用於展示api接口文檔 -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>RELEASE</version>
</dependency>
<!--增加兩個配置目的：訪問swagger後臺報錯處理-->
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.5.22</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>1.5.22</version>
</dependency>
2 spring集成配置
/**
* swagger
*
* @author l
* @date 20190820
*/
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
/**
* 創建Docket
*/
@Bean
public Docket createApi() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("api-user文檔")
// 去掉swagger默認的狀態碼
.useDefaultResponseMessages(false)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("cn.api.web.swagger"))
.paths(PathSelectors.any())
.build();
}
/**
* 構造ApiInfo
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("這是swagger的title")
.description("這是swagger的描述")
.version("1.0.0")
.contact(new Contact("張三", "", ""))
.build();
}
}
此時，即可訪問 http://{ip}:{port}/doc.html
3 controller
/**
* 用戶
*
* @author l
* @date 20190820
*/
@Slf4j
@RestController
@RequestMapping(value = "/api/user")
@Api(tags = "用戶相關")
public class UserController {
static Map<Integer, User> map = new HashMap<Integer, User>(){{
put(1, new User().setId(1).setName("張三").setPhone("13566669999"));
put(2, new User().setId(2).setName("李四").setPhone("15899996666"));
}};
/**
* 查詢用戶
*/
@GetMapping("/info")
/** 定義swagger中接口說明 */
@ApiOperation(value="根據id查詢用戶",notes="id必填，rest方式",consumes = "application/x-www-form-urlencoded")
/** 定義swagger中的請求參數 */
@ApiImplicitParams({
@ApiImplicitParam(name="id",value="id",required=true,paramType="query",dataType = "int")
})
/** 定義接口返回信息 */
@ApiResponses({@ApiResponse(code = 200,message = "OK")})
public Result<User> info(Integer id){
log.info("查詢id={}的用戶", id);
return Result.ok(map.get(id));
}
/**
* 查詢所有用戶
* swagger中的接口順序是以uri的字母順序生成
*/
@GetMapping("/all")
@ApiOperation(value="查詢所有用戶")
public Result<List<User>> getAll(){
List<User> list = new ArrayList<>();
for (Map.Entry<Integer, User> entry : map.entrySet()) {
list.add(entry.getValue());
}
return Result.ok(list);
}
}
4 實體類user
/**
* 用戶
*/
@Data
@Accessors(chain = true)
@ApiModel(description = "用戶實體")
public class User {
@ApiModelProperty(value = "主鍵")
private Integer id;
@ApiModelProperty(value = "姓名")
private String name;
@ApiModelProperty(value = "手機號")
private String phone;
}
5 實體類result
/**
* 返回實體
*/
@Data
@Accessors(chain = true)
@ApiModel(description = "返回實體")
public class Result<T> {
@ApiModelProperty(value = "狀態碼")
private Integer code;
@ApiModelProperty(value = "返回信息")
private String message;
@ApiModelProperty(value = "返回數據")
private T datas;
public static <T> Result<T> ok(T t){
return new Result<T>().setCode(200).setMessage("ok").setDatas(t);
}
}
6 具體效果圖：
主頁：
接口一：
接口二：
7 註解說明：
@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="int"
defaultValue：參數的默認值
@ApiResponses：用在請求的方法上，表示一組響應
@ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應信息
code：數字，例如400
message：信息，例如"請求參數沒填好"
response：拋出異常的類
@ApiModel：用於響應類上，表示一個返回響應數據的信息
@ApiModelProperty：用在屬性上，描述響應類的屬性
完.