為什么選擇knife4j
頁(yè)面好看，我放兩張對(duì)比圖
image
image
圖一是knife4j的官網(wǎng)延届，圖二是swagger默認(rèn)的界面恨胚。如果覺(jué)得第二章比第一張好看的，可以不用往下看了徘键。
如何使用
貼一下knife4j的官網(wǎng)：https://doc.xiaominfo.com/，里面有詳細(xì)的介紹遍蟋，這里只簡(jiǎn)單的介紹一下如何搭建吹害，先看一下簡(jiǎn)單的項(xiàng)目結(jié)構(gòu)
image
-
添加pom文件
<!--整合Knife4j--> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <version>3.0.3</version> </dependency>Knife4j里面集成了swagger的jar包，所以項(xiàng)目中有一個(gè)knife4j的jar包就能使用
-
添加配置文件
import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.ApiSelectorBuilder; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; /** * @Author nitric oxide * @Description * @Date 6:13 下午 2021/11/11 */ @EnableSwagger2 @Configuration public class SwaggerConfig { @Bean(value = "defaultApi2") public Docket defaultApi2() { ApiSelectorBuilder builder = new Docket(DocumentationType.SWAGGER_2) .enableUrlTemplating(false) .apiInfo(apiInfo()) // 選擇那些路徑和api會(huì)生成document .select() // 對(duì)所有api進(jìn)行監(jiān)控 .apis(RequestHandlerSelectors.any()) //這里可以自定義過(guò)濾 .paths(this::filterPath); return builder.build(); } private boolean filterPath(String path) { boolean ret = path.endsWith("/error"); if (ret) { return false; } //這塊可以寫(xiě)其他的過(guò)濾邏輯 return true; } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("title") .description("description") .termsOfServiceUrl("https://www.baidu.com") .version("1.0") .contact(new Contact("nitric oxide", "www.baidu.com", "123@qq.com")) .build(); } }
- 使用swagger注解標(biāo)記接口
image
image
-
最后訪(fǎng)問(wèn)http://ip:port/doc.html來(lái)看接口的效果
image
最后寫(xiě)一些swagger注解（不過(guò)我覺(jué)得上面的三個(gè)例子已經(jīng)覆蓋了大多數(shù)場(chǎng)景了）
| 作用范圍 | API | 使用位置 |
|---|---|---|
| 協(xié)議集描述 | @Api | controller類(lèi)上虚青，將一個(gè)class標(biāo)注為一個(gè)Swagger資源 |
| 協(xié)議描述 | @ApiOperation | controller方法上 |
| 非對(duì)象參數(shù)集 | @ApiImplicitParams | controller方法上 |
| 非對(duì)象參數(shù)描述 | @ApiImplicitParam | 用在@ApiImplicitParams的方法里邊 |
| 對(duì)象參數(shù)描述 | @ApiParam | 用在@ApiImplicitParams的方法里邊它呀，定義接收的參數(shù)形式 |
| 描述返回對(duì)象的意義 | @ApiModel | 用在返回對(duì)象類(lèi)上 |
| 對(duì)象屬性 | @ApiModelProperty | 用在參數(shù)對(duì)象的字段上 |
| Response集 | @ApiResponses | 用在controller的方法上 |
| Response | @ApiResponse | 用在 @ApiResponses里邊 |
詳細(xì)的介紹可以看這個(gè)鏈接
https://servicecomb.apache.org/references/java-chassis/zh_CN/build-provider/swagger-annotation.html
