Swagger“升级版”——knife4j

为什么选择knife4j

页面好看，我放两张对比图

image

image

图一是knife4j的官网，图二是swagger默认的界面。如果觉得第二章比第一张好看的，可以不用往下看了。

如何使用

贴一下knife4j的官网：https://doc.xiaominfo.com/，里面有详细的介绍，这里只简单的介绍一下如何搭建，先看一下简单的项目结构

image

1. 添加pom文件

   
   
       com.github.xiaoymin
       knife4j-spring-boot-starter
       3.0.3
   
   

   Knife4j里面集成了swagger的jar包，所以项目中有一个knife4j的jar包就能使用

2. 添加配置文件

   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", "[email protected]"))
                   .build();
       }
   }
   

3. 使用swagger注解标记接口

image

image

4. 最后访问http://ip:port/doc.html来看接口的效果

   image

最后写一些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