swagger2配置詳解

1.寫在controller上的注解

1.1 @Api

代碼

@Api(tags = "用戶相關接口", description = "提供用戶相關的 Rest API")

public class UserController

屬性解析

注解屬性	類型	描述
tags	String[]	控制器標簽。
description	String	控制器描述 （該字段被申明為過期）

2.寫在方法上的注解

2.1 接口方法的描述

@ApiOperation 主要屬性

代碼

@PostMapping(value = "/login")
    @ApiOperation(value = "登錄接口",notes = "登錄接口",httpMethod = "POST",responseContainer="登錄成功，登錄失敗")
    @ApiResponses({
            @ApiResponse(code = 200, message = "請求成功"),
            @ApiResponse(code = 10000, message = "用戶名驗證碼為空"),
            @ApiResponse(code = 10001, message = "驗證碼不正確"),
            @ApiResponse(code = 10002, message = "驗證碼已失效"),
            @ApiResponse(code = 10004, message = "登錄錯誤次數超過五次"),
            @ApiResponse(code = 10005, message = "用戶名或密碼錯誤"),
            @ApiResponse(code = 10006, message = "賬號被凍結,請聯系管理員")
    })
    public  ResponseEntity<Message<SystemAccountBean>> login(@RequestBody SystemAccountBeanVO systemAccountBean, HttpServletRequest request) {

        return ResponseEntity.ok(new Message(loginService.login(systemAccountBean, request)));

    }

屬性解析

注解屬性	類型	描述
value	String	接口說明。
notes	String	接口發布說明。
tags	Stirng[]	標簽。
response	Class<?>	接口返回類型。
httpMethod	String	接口請求方式。

@ApiIgnore

Swagger 文檔不會顯示擁有該注解的接口

@ApiImplicitParams

用於描述接口的非對象參數集

@ApiImplicitParam

用於描述接口的非對象參數，一般與 @ApiImplicitParams 組合使用。

@ApiImplicitParam

代碼示例

@ApiImplicitParams({
            @ApiImplicitParam(name = "accountId", value = "賬戶ID", dataType = "string", paramType = "query", example = "xingguo"),
    })
    public ResultMsgBean<List<SystemMenuBean>> queryForMenuListByAccountId() {
        return systemMenuBean;
    }

主要屬性

注解屬性	描述
paramType	查詢參數類型，實際上就是參數放在那里。取值： path：以地址的形式提交數據，根據 id查詢用戶的接口就是這種形式傳參。 query：Query string 的方式傳參。 header：以流的形式提交。 form：以 Form 表單的形式提交。
dataType	參數的數據類型。取值：Long String
name	參數名字。
value	參數意義的描述。
required	是否必填。取值：true：必填參數。false：非必填參數。

3.寫在實體類上的注解

3.1 描述

@ApiModel:

可設置接口相關實體的描述。

@ApiModelProperty:

可設置實體屬性的相關描述

3.2 代碼示例

@ApiModel(description= "賬戶信息類")
public class SystemAccountBean extends CustomerPersonBean {
	/** 帳號序號 */
	@ApiModelProperty(value="帳號序號")
	private String accountId;
}

3.3 @ApiModelProperty屬性說明

注解屬性	類型	描述
value	String	字段說明。
name	String	重寫字段名稱。
dataType	Stirng	重寫字段類型。
required	boolean	是否必填。
example	Stirng	舉例說明。
hidden	boolean	是否在文檔中隱藏該字段。
allowEmptyValue	boolean	是否允許為空。
allowableValues	String	該字段允許的值，當我們 API 的某個參數為枚舉類型時， 使用這個屬性就可以清楚地告訴 API 使用者該參數所能允許傳入的值。