springboot 整合 kettle springboot整合knife4j

转载

mob64ca14116c53 2024-03-29 11:55:21

文章标签 java springboot ci API spring 文章分类 架构后端开发

文章目录

Knif4j简介

概述
设计目标

Knif4j应用实践

准备工作
启动项目测试
应用实践分析

总结(Summary)

Knif4j简介

概述

knife4j是国人开发的一个基于Swagger2技术，为Java MVC框架生成Api文档的解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍!

设计目标

为前后端的开发人员的沟通提供便利手段。

Knif4j应用实践

准备工作

第一步：在springboot项目的配置文件中添加，如下依赖：

<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-spring-boot-starter -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.9</version>
</dependency>

第二步：在application.yml配置文件中添加如下配置：

knife4j:
   enable: true

第三步：创建配置类，例如：

/**
 * Knife4j（Swagger2）的配置
 */
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

    /**
     * 【重要】指定Controller包路径
     */
    private String basePackage = "cn.tedu.boot.demo.controller";
    /**
     * 分组名称
     */
    private String groupName = "xxx";
    /**
     * 主机名
     */
    private String host = "xxx";
    /**
     * 标题
     */
    private String title = "xxx";
    /**
     * 简介
     */
    private String description = "xxx";
    /**
     * 服务条款URL
     */
    private String termsOfServiceUrl = "http://www.apache.org/licenses/LICENSE-2.0";
    /**
     * 联系人
     */
    private String contactName = "xxx";
    /**
     * 联系网址
     */
    private String contactUrl = "xxx";
    /**
     * 联系邮箱
     */
    private String contactEmail = "xxx";
    /**
     * 版本号
     */
    private String version = "1.0.0";

    @Autowired
    private OpenApiExtensionResolver openApiExtensionResolver;

    @Bean
    public Docket docket() {
        String groupName = "1.0.0";
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .host(host)
                .apiInfo(apiInfo())
                .groupName(groupName)
                .select()
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                .paths(PathSelectors.any())
                .build()
                .extensions(openApiExtensionResolver.buildExtensions(groupName));
        return docket;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .termsOfServiceUrl(termsOfServiceUrl)
                .contact(new Contact(contactName, contactUrl, contactEmail))
                .version(version)
                .build();
    }

启动项目测试

完成后，启动项目，通过 http://localhost:8080/doc.html 即可访问在线API文档。

在开发实践中，每个处理请求的方法应该限定为某1种请求方式，如果允许多种请求方式，则在API文档的菜单中会有多项。

在API文档中，菜单中的各名称默认是根据控制器类名、方法名转换得到的，通常，应该通过配置改为更加易于阅读理解的名称：

@Api：是添加在控制器类上的注解，通过此注解的tags属性可以修改原本显示控制器类名称的位置的文本，通常，建议在配置的tags值上添加序号，例如：“1. 管理员模块”、“2. 商品模块”，则框架会根据值进行排序
@ApiOperation：是添加在控制器类中处理请求的方法上的注解，用于配置此方法处理的请求在API文档中显示的文本
@ApiOperationSupport：是添加在控制器类中处理请求的方法上的注解，通过配置其order属性可以指定各方法在API文档中的显示顺序
@ApiModelProperty：是添加在POJO类的属性上的注解，用于对请求参数或响应结果中的某个属性进行说明，主要通过其value属性配置描述文本，并可通过example属性配置示例值，还可在响应结果时通过position属性指定顺序
@ApiImplicitParam：是添加在控制器类中处理请求的方法上的注解，也可以作为@ApiImplicitParams注解的参数值，主要用于配置非封装的参数，主要配置name、value、example、required、dataType属性
@ApiImplicitParams：是添加在控制器类中处理请求的方法上的注解，当方法有多个非封装的参数时，在方法上添加此注解，并在注解内部通过@ApiImplicitParam数组配置多个参数

提示：以上@ApiImplicitParams、@ApiImplicitParam和@ApiModelProperty可以组合使用。

应用实践分析

在控制类上应用Knif4j，例如

@Api(tags = "1. 会员模块")
@Slf4j
@RestController
@RequestMapping("/member")
public class MemberController {

    @ApiOperationSupport(order = 10)
    @ApiOperation("会员注册")
    @PostMapping
    public String addNew(String username,String password) {
        throw new RuntimeException("此功能尚未实现");
    }

    @ApiOperationSupport(order = 40)
    @ApiOperation("查看会员详情")
    @ApiImplicitParam(name = "id", value = "会员id", example = "1",
            required = true, dataType = "long")
    @GetMapping("/{id:[0-9]+}")
    public Object getById(@PathVariable Long id) {
        throw new RuntimeException("此功能尚未实现");
    }

    @ApiOperationSupport(order = 41)
    @ApiOperation("根据城市和性别查询会员信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "city", value = "城市名", example = "1",
                required = true, dataType = "string"),
            @ApiImplicitParam(name = "gender", value = "性别", example = "1",
                dataType = "string")
    })
    @GetMapping("/listByExample")
    public Object listByExample(String city, String gender) {
        throw new RuntimeException("此功能尚未实现");
    }

}

配置示例–封装的POJO类：

@Data
@Accessors(chain = true)
public class MemberDTO implements Serializable {

    @ApiModelProperty(value = "用户名", example = "Mike")
    private String username;

    @ApiModelProperty(value = "密码", example = "123456")
    private String password;

    @ApiModelProperty(value = "昵称", example = "会员1号")
    private String nickname;

}