SpringBoot中使用Knife4J的解決方案

第SpringBoot中使用Knife4J的解決方案目錄一、引入依賴二、創(chuàng)建配置類三、常用注解3-1@Api3-1-1@Api注解的常用屬性，如下：3-1-2@Api注解的不常用屬性，如下：3-2@ApiOperation3-2-1@ApiOperation注解的常用屬性，如下：3-2-2@ApiOperation注解的不常用屬性，如下：3-3@ApiImplicitParam3-3-1@ApiImplicitParam注解的常用屬性，如下：3-3-2@ApiImplicitParam注解的不常用屬性，如下：3-4@ApiModel3-4-1@ApiModel注解的常用屬性，如下：3-5@ApiModelProperty3-5-1@ApiModelProperty注解的常用屬性，如下：3-5-2@ApiModelProperty注解的不常用屬性，如下：3-6@ApiResponse四、配置JavaBean五、配置Controller六、接口文檔預(yù)覽knife4j是為JavaMVC框架集成Swagger生成Api文檔的增強解決方案。

knife4j的前身是swagger-bootstrap-ui，為了契合微服務(wù)的架構(gòu)發(fā)展，由于原來swagger-bootstrap-ui采用的是后端Java代碼+前端Ui混合打包的方式,在微服務(wù)架構(gòu)下顯的很臃腫，因此項目正式更名為knife4j。knife4j官方網(wǎng)址：knife4j

一、引入依賴

Knife4J官網(wǎng)：

/

快速開始：/docs/quick-start

!--引入Knife4j的官方start包,Swagger2基于Springfox2.10.5項目--

dependency

groupIdcom.github.xiaoymin/groupId

!--使用Swagger2--

artifactIdknife4j-spring-boot-starter/artifactId

version2.0.9/version

/dependency

二、創(chuàng)建配置類

創(chuàng)建config包，在其中新建一個配置類：

@Configuration

@EnableSwagger2WebMvc

publicclassKnife4jConfiguration{

@Bean(value="dockerBean")

publicDocketdockerBean(){

//指定使用Swagger2規(guī)范

Docketdocket=newDocket(DocumentationType.SWAGGER_2)

.apiInfo(newApiInfoBuilder()

//描述字段支持Markdown語法

.description("#寫一個簡要的描述")

.termsOfServiceUrl("/")

.contact("可以寫作者的信息")

.version("1.0")

.build())

//分組名稱

.groupName("用戶服務(wù)")

.select()

//這里指定Controller掃描包路徑

.apis(RequestHandlerSelectors.basePackage("com.xueou.boot.controller"))

.paths(PathSelectors.any())

.build();

returndocket;

最重要的配置還是：指定Controller掃描包路徑contact

官方是棄用了直接傳字符串的這個設(shè)置方法，改用傳入一個Contact類，看一下源碼可以發(fā)現(xiàn)該類的結(jié)構(gòu)（內(nèi)容更豐富了：姓名、郵箱、URL連接）

三、常用注解

3-1@Api

@Api注解，添加在Controller類上，標記它作為Swagger文檔資源。

3-1-1@Api注解的常用屬性，如下：

tags屬性：用于控制API所屬的標簽列表。[]數(shù)組，可以填寫多個?？梢栽谝粋€Controller上的@Api的tags屬性，設(shè)置多個標簽，那么這個Controller下的API接口，就會出現(xiàn)在這兩個標簽中。如果在多個Controller上的@Api的tags屬性，設(shè)置一個標簽，那么這些Controller下的API接口，僅會出現(xiàn)在這一個標簽中。本質(zhì)上，tags就是為了分組API接口，和Controller本質(zhì)上是一個目的。所以絕大數(shù)場景下，我們只會給一個Controller一個唯一的標簽。

3-1-2@Api注解的不常用屬性，如下：

produces屬性：請求請求頭的可接受類型(Accept)。如果有多個，使用,分隔。consumes屬性：請求請求頭的提交內(nèi)容類型(Content-Type)。如果有多個，使用,分隔。protocols屬性：協(xié)議，可選值為http、https、ws、wss。如果有多個，使用,分隔。authorizations屬性：授權(quán)相關(guān)的配置，[]數(shù)組，使用@Authorization注解。hidden屬性：是否隱藏，不再API接口文檔中顯示。

@Api注解的廢棄屬性，不建議使用，有value、description、basePath、position。

3-2@ApiOperation

@ApiOperation注解，添加在Controller方法上，標記它是一個API操作。

3-2-1@ApiOperation注解的常用屬性，如下：

value屬性：API操作名。notes屬性：API操作的描述。

3-2-2@ApiOperation注解的不常用屬性，如下：

tags屬性：和@API注解的tags屬性一致。nickname屬性：API操作接口的唯一標識，主要用于和第三方工具做對接。httpMethod屬性：請求方法，可選值為GET、HEAD、POST、PUT、DELETE、OPTIONS、PATCH。因為Swagger會解析SpringMVC的注解，所以一般無需填寫。produces屬性：和@API注解的produces屬性一致。consumes屬性：和@API注解的consumes屬性一致。protocols屬性：和@API注解的protocols屬性一致。authorizations屬性：和@API注解的authorizations屬性一致。hidden屬性：和@API注解的hidden屬性一致。response屬性：響應(yīng)結(jié)果類型。因為Swagger會解析方法的返回類型，所以一般無需填寫。responseContainer屬性：響應(yīng)結(jié)果的容器，可選值為List、Set、Map。responseReference屬性：指定對響應(yīng)類型的引用。這個引用可以是本地，也可以是遠程。并且，當設(shè)置了它時，會覆蓋response屬性。說人話，就是可以忽略這個屬性，哈哈哈。responseHeaders屬性：響應(yīng)頭，[]數(shù)組，使用@ResponseHeader注解。code屬性：響應(yīng)狀態(tài)碼，默認為200。extensions屬性：拓展屬性，[]屬性，使用@Extension注解。ignoreJsonView屬性：在解析操作和類型，忽略JsonView注釋。主要是為了向后兼容。

@ApiOperation注解的廢棄屬性，不建議使用，有position。

3-3@ApiImplicitParam

@ApiImplicitParam注解，添加在Controller方法上，聲明每個請求參數(shù)的信息。

3-3-1@ApiImplicitParam注解的常用屬性，如下：

name屬性：參數(shù)名。value屬性：參數(shù)的簡要說明。required屬性：是否為必傳參數(shù)。默認為false。dataType屬性：數(shù)據(jù)類型，通過字符串String定義。dataTypeClass屬性：數(shù)據(jù)類型，通過dataTypeClass定義。在設(shè)置了dataTypeClass屬性的情況下，會覆蓋dataType屬性。推薦采用這個方式。paramType屬性：參數(shù)所在位置的類型。有如下5種方式：

path值：對應(yīng)SpringMVC的@PathVariable注解。

【默認值】query值：對應(yīng)SpringMVC的@PathVariable注解。

body值：對應(yīng)SpringMVC的@RequestBody注解。

header值：對應(yīng)SpringMVC的@RequestHeader注解。

form值：Form表單提交，對應(yīng)SpringMVC的@PathVariable注解。

絕大多數(shù)情況下，使用query值這個類型即可。

example屬性：參數(shù)值的簡單示例。examples屬性：參數(shù)值的復(fù)雜示例，使用@Example注解。

3-3-2@ApiImplicitParam注解的不常用屬性，如下：

defaultValue屬性：默認值。allowableValues屬性：允許的值。如果要設(shè)置多個值，有兩種方式：

數(shù)組方式，即{value1,value2,value3}。例如說，{1,2,3}。

范圍方式，即[value1,value2]或[value1,value2)。例如說[1,5]表示1到5的所有數(shù)字。如果有無窮的，可以使用(-infinity,value2]或[value1,infinity)。

allowEmptyValue屬性：是否允許空值。allowMultiple屬性：是否允許通過多次傳遞該參數(shù)來接受多個值。默認為false。type屬性：搞不懂具體用途，對應(yīng)英文注釋為Addstheabilitytooverridethedetectedtype。readOnly屬性：是否只讀。format屬性：自定義的格式化。collectionFormat屬性：針對Collection集合的，自定義的格式化。

當我們需要添加在方法上添加多個@ApiImplicitParam注解時，可以使用@ApiImplicitParams注解中添加多個。

3-4@ApiModel

@ApiModel注解，添加在POJO類，聲明POJO類的信息。而在Swagger中，把這種POJO類稱為Model類。所以，我們下文就統(tǒng)一這么稱呼。

3-4-1@ApiModel注解的常用屬性，如下：

value屬性：Model名字。description屬性：Model描述。

3-4-2@ApiModel注解的不常用屬性，如下：

parent屬性：指定該Model的父Class類，用于繼承父Class的Swagger信息。subTypes屬性：定義該Model類的子類Class們。discriminator屬性：搞不懂具體用途，對應(yīng)英文注釋為Supportsmodelinheritanceandpolymorphism.reference屬性：搞不懂具體用途，對應(yīng)英文注釋為Specifiesareferencetothecorrespondingtypedefinition,overridesanyothermetadataspecified

3-5@ApiModelProperty

@ApiModelProperty注解，添加在Model類的成員變量上，聲明每個成員變量的信息。

3-5-1@ApiModelProperty注解的常用屬性，如下：

value屬性：屬性的描述。dataType屬性：和@ApiImplicitParam注解的dataType屬性一致。不過因為@ApiModelProperty是添加在成員變量上，可以自動獲得成員變量的類型。required屬性：和@ApiImplicitParam注解的required屬性一致。example屬性：@ApiImplicitParam注解的example屬性一致。

3-5-2@ApiModelProperty注解的不常用屬性，如下：

name屬性：覆蓋成員變量的名字，使用該屬性進行自定義。allowableValues屬性：和@ApiImplicitParam注解的allowableValues屬性一致。position屬性：成員變量排序位置，默認為0。hidden屬性：@ApiImplicitParam注解的hidden屬性一致。accessMode屬性：訪問模式，有AccessMode.AUTO、AccessMode.READ_ONLY、AccessMode.READ_WRITE三種，默認為AccessMode.AUTO。reference屬性：和@ApiModel注解的reference屬性一致。allowEmptyValue屬性：和@ApiImplicitParam注解的allowEmptyValue屬性一致。extensions屬性：和@ApiImplicitParam注解的extensions屬性一致。

@ApiModelProperty注解的廢棄屬性，不建議使用，有readOnly。

3-6@ApiResponse

在大多數(shù)情況下，我們并不需要使用@ApiResponse注解，因為我們會類似UserController#get(id)方法這個接口，返回一個Model即可。

@ApiResponse注解，添加在Controller類的方法上，聲明每個響應(yīng)參數(shù)的信息。@ApiResponse注解的屬性，基本已經(jīng)被@ApiOperation注解所覆蓋，如下：message屬性：響應(yīng)的提示內(nèi)容。code屬性：和@ApiOperation注解的code屬性一致。response屬性：和@ApiOperation注解的response屬性一致。reference屬性：和@ApiOperation注解的responseReference屬性一致。responseHeaders屬性：和@ApiOperation注解的responseHeaders屬性一致。responseContainer屬性：和@ApiOperation注解的responseContainer屬性一致。examples屬性：和@ApiOperation注解的examples屬性一致。

當我們需要添加在方法上添加多個@ApiResponse注解時，可以使用@ApiResponses注解中添加多個。

四、配置JavaBean

主要用于返回參數(shù)、或是接收參數(shù)的時候進行說明。

@Getter

@Setter

@ToString

@NoArgsConstructor

@ApiModel(value="輪播圖對象",description="")

publicclassBannerimplementsSerializable{

@ApiModelProperty(value="id",example="1")

@TableId(value="id",type=IdType.AUTO)

privateIntegerid;

@ApiModelProperty(value="圖像鏈接",example="https://xxx/xxx.png")

privateStringimgUrl;

@ApiModelProperty(value="標題",example="這是一個標題喲~")

privateStringtitle;

我自己用的時候，又封裝了一層，設(shè)置了幾個JavaBean用于包裝返回的響應(yīng)結(jié)果：

分別用于返回單個數(shù)據(jù)、數(shù)據(jù)列表，同時附帶上狀態(tài)碼和說明信息。

@Data

@ToString

@AllArgsConstructor

@NoArgsConstructor

publicabstractclassRBean{

@ApiModelProperty(value="響應(yīng)碼",

position=0,

example="200",

notes="200:成功；500：失?。?)

privateIntegercode;

@ApiModelProperty(value="響應(yīng)說明",position=1,example="xx數(shù)據(jù)獲取成功。")

privateStringmsg;

//=====================

@EqualsAndHashCode(callSuper=true)

@Data

@ToString

@AllArgsConstructor

@NoArgsConstructor

publicclassROneBeanTextendsRBean{

@ApiModelProperty(value="數(shù)據(jù)項",position=2)

privateTdata;

//=======================

@EqualsAndHashCode(callSuper=true)

@Data

@ToString

@AllArgsConstructor

@NoArgsConstructor

publicclassRListBeanTextendsRBean{

@ApiModelProperty(value="數(shù)據(jù)列表",position=2)

privateListTdata;

五、配置Controller

潦草的寫幾個接口

@Api(tags="首頁模塊")

@RestController

publicclassIndexController{

@Resource

IBannerServiceiBannerService;

@ApiOperation(value="域名直接轉(zhuǎn)接口文檔",hidden=true)

@GetMapping("/")

publicvoidtoDoc(HttpServletResponseresponse)throwsIOException{

response.sendRedirect("/doc.html");

@ApiOperation("新增輪播圖數(shù)據(jù)")

@PostMapping("/addBanners")

publicvoidputBanne