zlprime zlprime
  • 首页
  • 朝花夕拾
    • 摄影
    • 读书
    • 生活
    • 随笔
  • 技能分享
    • WordPress
  • 其它
    • 游记地图
    • 闲言碎语
    • 阅读书单
    • 友情链接
    • 留言板
  • Java
首页 › Java › Knife4J的基本使用

Knife4J的基本使用

Stone
6月前Java
745 4 1

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生成的接口文档


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

java java框架 spring
1
本文系作者 @Stone 原创发布在 zlprime。未经许可,禁止转载。
Swagger的基本使用
上一篇
集合之Collection集合入门
下一篇
评论 (4)
再想想
  • 张三

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

    2月前     Windows /    Chrome
    • Stone

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

      1月前     MacOS /    Chrome
  • 2broear

    我们需要生活文章扇耳光

    6月前     Windows /    Chrome
    • Stone

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

      6月前     MacOS /    Chrome
聚合文章
JDBC的使用总结
5月前
Centos8中安装RabbitMQ
5月前
集合之Map集合
5月前
Collections集合工具类和可变参数
5月前
相关文章
JDBC的使用总结
Centos8中安装RabbitMQ
集合之Map集合
Collections集合工具类和可变参数
简介

海边微风起,等风也等你

留言板
留言板
小伙伴们
2Broear Libra の 向往 云帆沧海 若志随笔 豆豆 Chuanbo
Copyright © 2017-2023 zlprime. 皖ICP备17019582号
  • 首页
  • 朝花夕拾
    • 摄影
    • 读书
    • 生活
    • 随笔
  • 技能分享
    • WordPress
  • 其它
    • 游记地图
    • 闲言碎语
    • 阅读书单
    • 友情链接
    • 留言板
热门搜索
  • java
  • spring
Stone
67 文章
139 评论
83 喜欢
  • 1
  • 4
  • Top