Swagger“升级版”——knife4j - 简书

为什么选择knife4j

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

image

image

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

如何使用

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

image

  1. 添加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包就能使用

  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
 */
@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();
    }
}

```
  1. 使用swagger注解标记接口

image

image

  1. 最后访问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

原网址: 访问
创建于: 2023-04-26 20:04:24
目录: default
标签: 无

未标明原创文章均为采集，版权归作者所有，转载无需和我联系，请注明原出处，南摩阿彌陀佛，知识，不只知道，要得到

请先后发表评论
  • 最新评论
  • 总共0条评论