心耘博客 | ZLPRIME-磊落平生志,破浪去乘风 心耘博客 | ZLPRIME-磊落平生志,破浪去乘风
  • 首页
  • 朝花夕拾
    • 光影记录
    • 生活随笔
  • 代码如诗
    • 100 Days of SwiftUI
    • 后端技术
    • 服务器配置
  • 影集
  • 关于我
  • 更多
    • 专题汇总
    • 友情链接
    • 留言板
  • 1
  • 4

Knife4J的基本使用

心耘
3 年前

knife4J是对Swagger的增强解决方案,其底层封装了springFox,使用方式也和SpringFox一致,但是对接口文档的UI进行了优化

1.要使用Knife4J首先要导入相应的坐标:

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

2.然后创建User实体类

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "用户实体",description = "用户实体")
public class User {
    @ApiModelProperty(value = "主键")
    private int id;
    @ApiModelProperty(value = "姓名")
    private String name;
    @ApiModelProperty(value = "年龄")
    private Integer age;
    @ApiModelProperty(value = "地址")
    private String address;
}

3.然后创建UserController控制类

@RestController
@RequestMapping("/users")
@Api(tags = "用户控制器")
public class UserController {
    @GetMapping
    @ApiOperation(value = "查询所有用户",notes = "查询所有用户信息")
    public List<User> getAllUsers(){
        User user = new User();
        user.setId(100);
        user.setName("zhang");
        user.setAge(27);
        user.setAddress("安徽省合肥市");
        List<User> users = new ArrayList<>();
        users.add(user);
        return users;
    }
    @DeleteMapping("/{id}")
    @ApiImplicitParams(
            @ApiImplicitParam(name = "id",value = "用户编号",required = true,type = "Integer")
    )
    @ApiOperation(value = "删除用户", notes = "删除用户信息")
    public String delete(@PathVariable int id){
        return "OK";
    }
 }

4.通过项目的application.yml配置文件对knife4J的参数进行配置,可以让我们的程序进一步解耦。通过读取yml文件中的配置信息,我们可以在不修改源码的情况下对接口文档的一些参数进行调整。首先,我们要在yml文件中添加一下配置信息:

server:
  port: 9001

swagger:
  title: 测试文档标题
  base-package: cn.zlprime
  docket:
    api1:
      title: 标题1
    api2:
      title: 标题2
      version: 2.2.2.2

5.编写配置属性类读取yml文件信息并封装起来

@ConfigurationProperties(prefix = "swagger")
@Data
public class SwaggerProperties {

    private String title="knife4j接口文档";
    private String group="";
    private String version="1.1";
    private String description="这是一个UI经过优化的接口文档";
    private Contact contact = new Contact();
    private String basePackage="com.zlprime";
    private Map<String,DocketInfo> docket  = new LinkedHashMap<>();

    public String getGroup(){
        if(group!=null || "".equals(group)){
            return group;
        }
        return title;
    }

    @Data
    public static class DocketInfo{
        private String title="knife4j接口文档";
        private String group="";
        private String version="1.1";
        private String description="这是一个UI经过优化的接口文档";
        private String basePackage="com.zlprime";
        private Contact contact = new Contact();
        public String getGroup(){
            if(group!=null || "".equals(group)){
                return group;
            }
            return title;
        }
    }

    @Data
    public static class Contact{
        private String name="zlprime";
        private String url="https://www.zlprime.cn";
        private String email="zl_al@live.com";
    }
}

6.编写Knife4J的配置类

@Configuration
@EnableSwagger2  //开启Swagger2,这个注解很关键
@EnableConfigurationProperties(SwaggerProperties.class)
public class SwaggerAutoConfiguration implements BeanFactoryAware {

    @Autowired
    SwaggerProperties swaggerProperties;

    private BeanFactory beanFactory;

    @Bean
    @ConditionalOnMissingBean
    public List<Docket> getRestApi(){
        ConfigurableBeanFactory configurableBeanFactory =
                (ConfigurableBeanFactory) beanFactory;
        List<Docket> docketList = new LinkedList<>();
        // 没有分组
        if (swaggerProperties.getDocket().isEmpty()) {
            Docket docket = createDocket(swaggerProperties);
            configurableBeanFactory.registerSingleton(swaggerProperties.getTitle(),
                    docket);
            docketList.add(docket);
            return docketList;
        }
        // 分组创建
        for (String groupName : swaggerProperties.getDocket().keySet()){
            SwaggerProperties.DocketInfo docketInfo =
                    swaggerProperties.getDocket().get(groupName);
            ApiInfo apiInfo = new ApiInfoBuilder()
                    //页面标题
                    .title(docketInfo.getTitle())
                    //创建人
                    .contact(new Contact(docketInfo.getContact().getName(),
                            docketInfo.getContact().getUrl(),
                            docketInfo.getContact().getEmail()))
                    //版本号
                    .version(docketInfo.getVersion())
                    //描述
                    .description(docketInfo.getDescription())
                    .build();

            Docket docket = new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo)
                    .groupName(docketInfo.getGroup())
                    .select()
                    //为当前包路径
                    .apis(RequestHandlerSelectors.basePackage(docketInfo.getBasePackage()))
                    .build();
            configurableBeanFactory.registerSingleton(groupName, docket);
            docketList.add(docket);
        }
        return docketList;
    }

    private ApiInfo apiInfo(SwaggerProperties swaggerProperties) {
        return new ApiInfoBuilder()
                //页面标题
                .title(swaggerProperties.getTitle())
                //创建人
                .contact(new Contact(swaggerProperties.getContact().getName(),
                        swaggerProperties.getContact().getUrl(),
                        swaggerProperties.getContact().getEmail()))
                //版本号
                .version(swaggerProperties.getVersion())
                //描述
                .description(swaggerProperties.getDescription())
                .build();
    }

    //创建接口文档对象
    private Docket createDocket(SwaggerProperties swaggerProperties) {
        //API 基础信息
        ApiInfo apiInfo = apiInfo(swaggerProperties);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .groupName(swaggerProperties.getGroup())
                .select()
                .apis(RequestHandlerSelectors.basePackage(swaggerProperties.getBasePackage()))
                .build();
    }

    @Override
    public void setBeanFactory(BeanFactory beanFactory) throws BeansException {
        this.beanFactory = beanFactory;
    }
}

7.最后创建SpringBoot的启动类,启动程序

@SpringBootApplication
public class SwaggegrApplication {
    public static void main(String[] args) {
        SpringApplication.run(SwaggegrApplication.class);
    }
}

启动程序,在浏览器中输入 localhost:9001/doc.html ,即可看到knife4J生成的接口文档

Knife4J的基本使用

最新:本方法中,配置接口分组已失效

java spring
1
Swagger的基本使用
上一篇
Mac M1芯片无法运行nacos 2.x版本
下一篇

评论 (4)

再想想
  • 张三

    List 并没有生效是怎么回事?

    2 年前 未知地区
    • Stone

      @张三: 确实没生效,我这个方法是老版本的配置类方法了。新版本的没研究过,项目上也没用到分类,就没管了。

      2 年前 未知地区
  • 2broear

    我们需要生活文章@(扇耳光)

    3 年前 未知地区
    • Stone

      @2broear: 换了个主机,竟然邮件通知失效了,现在应该可以了

      3 年前 未知地区

心耘

73
文章
167
评论
94
喜欢

标签

centos (13) java (22) jenkins (7) linux (12) lombok (1) maven (1) mysql (3) redis (2) rocky linux (3) spring (8) wordpress (5) 发布 (3) 实用技巧 (7) 教程 (6) 服务器配置 (3) 生活 (5) 部署 (2)

聚合文章

生活杂记(一)
家电选购小结-空调
十一带娃心得
通过War包升级Jenkins版本

专题推荐

7

Jenkins合集

12

服务器配置

猜你喜欢

通过War包升级Jenkins版本

通过War包升级Jenkins版本

1 年前
429 0 0
配置Jmeter的Perfmon插件

配置Jmeter的Perfmon插件

2 年前
556 0 0
为JMeter安装插件

为JMeter安装插件

2 年前
555 0 0
Mac中安装并启动Jmeter

Mac中安装并启动Jmeter

2 年前
729 0 2
4 1

简介

海边微风起,等风也等你

留言板

留言板

小伙伴们

2Broear 乙末博客 若志随笔 豆豆 诗意笔记 元のDiary
Copyright © 2017-2025 心耘博客 | ZLPRIME-磊落平生志,破浪去乘风. 皖ICP备17019582号
  • 首页
  • 朝花夕拾
    • 光影记录
    • 生活随笔
  • 代码如诗
    • 100 Days of SwiftUI
    • 后端技术
    • 服务器配置
  • 影集
  • 关于我
  • 更多
    • 专题汇总
    • 友情链接
    • 留言板

搜索

  • java
  • spring

心耘

73
文章
167
评论
94
喜欢