为什么选择knife4j
页面好看,我放两张对比图
图一是knife4j的官网,图二是swagger默认的界面。如果觉得第二章比第一张好看的,可以不用往下看了。
如何使用
贴一下knife4j的官网:https://doc.xiaominfo.com/,里面有详细的介绍,这里只简单的介绍一下如何搭建,先看一下简单的项目结构
-
添加pom文件
<!--整合Knife4j--> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <version>3.0.3</version> </dependency>
Knife4j里面集成了swagger的jar包,所以项目中有一个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会生成document .select() // 对所有api进行监控 .apis(RequestHandlerSelectors.any()) //这里可以自定义过滤 .paths(this::filterPath); return builder.build(); } private boolean filterPath(String path) { boolean ret = path.endsWith("/error"); if (ret) { return false; } //这块可以写其他的过滤逻辑 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注解标记接口
-
最后访问http://ip:port/doc.html来看接口的效果
最后写一些swagger注解(不过我觉得上面的三个例子已经覆盖了大多数场景了)
作用范围 | API | 使用位置 |
---|---|---|
协议集描述 | @Api | controller类上,将一个class标注为一个Swagger资源 |
协议描述 | @ApiOperation | controller方法上 |
非对象参数集 | @ApiImplicitParams | controller方法上 |
非对象参数描述 | @ApiImplicitParam | 用在@ApiImplicitParams的方法里边 |
对象参数描述 | @ApiParam | 用在@ApiImplicitParams的方法里边,定义接收的参数形式 |
描述返回对象的意义 | @ApiModel | 用在返回对象类上 |
对象属性 | @ApiModelProperty | 用在参数对象的字段上 |
Response集 | @ApiResponses | 用在controller的方法上 |
Response | @ApiResponse | 用在 @ApiResponses里边 |
详细的介绍可以看这个链接
https://servicecomb.apache.org/references/java-chassis/zh_CN/build-provider/swagger-annotation.html