springboot集成knife4j 实现优雅接口文档

springboot集成knife4j 

一：knife4j 是什么？有什么用

knife4g是为Java 框架集成Swagger生成Api文档的解决方案，而且是一款国产开源的API接口文档

在线查看工具。可以帮助前后端开发人员更好地进行接口联调工作。

二：如何使用knife4g？

针对springboot项目， 我们进行knife4g集成，即可使用。

1：在pom文件引入knife4g插件

注意 knife4g版本和springboot 之间的版本是否匹配 ，我这里使用的都是2开头版本

    

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.8</version>
        </dependency>

2： 设置knife4g的相关属性

这一步是为了后续配置类的属性从此处取值，只做简单展示，解耦合，可省略。

# yml 配置文件

knie4j:
  # true 表示开启 ，false表示关闭      
  enabled: true

3：创建配置类

相关要点在代码里已说明，就不多做解释

@Configuration
@EnableSwagger2
@EnableKnife4j
public class Knife4jConfig {
    /** 是否开启swagger */
    @Value("${knife4j.enabled}")
    private boolean enabled;

    @Bean(value = "knefi4g")
    public Docket knefi4g() {
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                // 是否启用knife4j
                .enable(enabled)
                .apiInfo(new ApiInfoBuilder()
                        .description("# knefi4g在线接口文档测试")
                        .contact("demo")
                        .version("1.0")
                        .build())
                //分组名称
                .groupName("1.0版本")
                .select()
                //这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.demo.api"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
}

4：接口类实现knife4g配置

 1：首先在控制器层（Controller） 上加入标题注解 （@Api）

 2：在每个接口上加入接口说明注解 （ @ApiOperatio )

 3：get 请求 添加 ApiImplicitParam注解

 4：在对象类添加相关注解,这样在接口文档就可以看到返回对象的描述说明

 5：启动项目，访问接口文档地址：   localhost:端口号/doc.html 

@Api(tags = "测试类相关接口")
@RestController
@RequestMapping("/demo")
public class demoController{








   @ApiOperation(value = "单条件查询接口")
   @GetMapping("/query")
   @ApiImplicitParam(name ="id",value = "参数",required = true)
   public ResultData< List<Model> > query(@RequestParam("id") String id){

         List<Model> list=new ArrayList();
         return ResultData.success(list);
    }


    @ApiOperation(value = "多条件查询接口")
    @GetMapping("/query")
    @ApiImplicitParams({
           @ApiImplicitParam(name ="id",value = "参数一",required = true),
           @ApiImplicitParam(name ="name",value = "参数二",required = false)

    })
   public ResultData< List<Model> > query(@RequestParam("id") String id,@RequestParam("name") String name){

         List<Model> list=new ArrayList();
         return ResultData.success(list);
    }




    @ApiOperation(value = "保存接口")
    @ResponseBody
    @PostMapping("/save")
    public ResultData save(@RequestBody Modelparam){

        return ResultData.success("保存成功");

    }




@Data
@ApiModel(description = "参数信息",value = "Model")
public class Model{


    /**id */
    @ApiModelProperty(value = "参数id")
    private Long id;

}


}

效果如下：

另，想具体研究knife4g，可查看官方文档   knife4g官方文档 。

其中，还有许多接口测试工具，比如

apifox

postman ,postwoman 等等，有兴趣的可以自行参考。其实不管什么类型接口文档，大家使用久了

都会习惯，欢迎大家互相交流讨论。

好了，本章文章到此结束。