文章详情

短信预约-IT技能 免费直播动态提醒

请输入下面的图形验证码

提交验证

短信预约提醒成功

SpringBoot中使用Knife4J的解决方案

2024-04-02 19:55

关注

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案。

knife4j的前身是swagger-bootstrap-ui,为了契合微服务的架构发展,由于原来swagger-bootstrap-ui采用的是后端Java代码+前端Ui混合打包的方式,在微服务架构下显的很臃肿,因此项目正式更名为knife4j。 knife4j官方网址:knife4j

一、引入依赖

Knife4J 官网:

https://doc.xiaominfo.com/
快速开始:https://doc.xiaominfo.com/docs/quick-start
<!--引入Knife4j的官方start包,Swagger2基于Springfox2.10.5项目-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <!--使用Swagger2-->
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.9</version>
</dependency>

二、创建配置类

创建config包,在其中新建一个配置类:

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

    @Bean(value = "dockerBean")
    public Docket dockerBean() {
        //指定使用Swagger2规范
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                //描述字段支持Markdown语法
                .description("# 写一个简要的描述")
                .termsOfServiceUrl("https://doc.xiaominfo.com/")
                .contact("可以写作者的信息")
                .version("1.0")
                .build())
                //分组名称
                .groupName("用户服务")
                .select()
                //这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.xueou.boot.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
}

官方是弃用了直接传字符串的这个设置方法,改用传入一个Contact类,看一下源码可以发现该类的结构(内容更丰富了:姓名、邮箱、URL连接)

三、常用注解

3-1 @Api

@Api 注解,添加在 Controller 类上,标记它作为 Swagger 文档资源。

3-1-1 @Api 注解的常用属性,如下:

3-1-2 @Api 注解的不常用属性,如下:

@Api 注解的废弃属性,不建议使用,有 value、description、basePath、position 。

3-2 @ApiOperation

@ApiOperation 注解,添加在 Controller 方法上,标记它是一个 API 操作。

3-2-1 @ApiOperation 注解的常用属性,如下:

3-2-2 @ApiOperation 注解的不常用属性,如下:

@ApiOperation 注解的废弃属性,不建议使用,有 position 。

3-3 @ApiImplicitParam

@ApiImplicitParam 注解,添加在 Controller 方法上,声明每个请求参数的信息。

3-3-1 @ApiImplicitParam 注解的常用属性,如下:

"path" 值:对应 SpringMVC 的 @PathVariable 注解。
【默认值】"query" 值:对应 SpringMVC 的 @PathVariable 注解。
"body" 值:对应 SpringMVC 的 @RequestBody 注解。
"header" 值:对应 SpringMVC 的 @RequestHeader 注解。
"form" 值:Form 表单提交,对应 SpringMVC 的 @PathVariable 注解。
绝大多数情况下,使用 “query” 值这个类型即可。

3-3-2 @ApiImplicitParam 注解的不常用属性,如下:

数组方式,即 {value1, value2, value3} 。例如说,{1, 2, 3} 。
范围方式,即 [value1, value2][value1, value2) 。例如说 [1, 5] 表示 1 到 5 的所有数字。如果有无穷的,可以使用 (-infinity, value2][value1, infinity)

当我们需要添加在方法上添加多个 @ApiImplicitParam 注解时,可以使用 @ApiImplicitParams 注解中添加多个。

3-4 @ApiModel

@ApiModel 注解,添加在 POJO 类,声明 POJO 类的信息。而在 Swagger 中,把这种 POJO 类称为 Model 类。所以,我们下文就统一这么称呼。

3-4-1 @ApiModel 注解的常用属性,如下:

3-4-2 @ApiModel 注解的不常用属性,如下:

3-5 @ApiModelProperty

3-5-1 @ApiModelProperty 注解的常用属性,如下:

3-5-2 @ApiModelProperty 注解的不常用属性,如下:

@ApiModelProperty 注解的废弃属性,不建议使用,有 readOnly 。

3-6 @ApiResponse

在大多数情况下,我们并不需要使用 @ApiResponse 注解,因为我们会类似 UserController#get(id) 方法这个接口,返回一个 Model 即可。

当我们需要添加在方法上添加多个 @ApiResponse 注解时,可以使用 @ApiResponses 注解中添加多个。

四、配置JavaBean

主要用于返回参数、或是接收参数的时候进行说明。

@Getter
@Setter
@ToString
@NoArgsConstructor
@ApiModel(value = "轮播图对象", description = "")
public class Banner implements Serializable {
    @ApiModelProperty(value = "id", example = "1")
    @TableId(value = "id", type = IdType.AUTO)
    private Integer id;
    @ApiModelProperty(value = "图像链接", example = "https://xxx/xxx.png")
    private String imgUrl;
    @ApiModelProperty(value = "", example = "这是一个哟~")
    private String title;
}

我自己用的时候,又封装了一层,设置了几个JavaBean用于包装返回的响应结果:

分别用于返回单个数据、数据列表,同时附带上状态码和说明信息。

@Data
@ToString
@AllArgsConstructor
@NoArgsConstructor
public abstract class RBean {
    @ApiModelProperty(value = "响应码",
            position = 0,
            example = "200",
            notes = "200: 成功;500:失败;")
    private Integer code;
    @ApiModelProperty(value = "响应说明", position = 1, example = "xx数据获取成功。")
    private String msg;
}

// =====================
@EqualsAndHashCode(callSuper=true)
@Data
@ToString
@AllArgsConstructor
@NoArgsConstructor
public class ROneBean<T> extends RBean {

    @ApiModelProperty(value = "数据项", position = 2)
    private T data;
}

// =======================
@EqualsAndHashCode(callSuper=true)
@Data
@ToString
@AllArgsConstructor
@NoArgsConstructor
public class RListBean<T> extends RBean{
    @ApiModelProperty(value = "数据列表", position = 2)
    private List<T> data;
}

五、配置Controller

潦草的写几个接口

@Api(tags = "首页模块")
@RestController
public class IndexController {
    @Resource
    IBannerService iBannerService;

    @ApiOperation(value = "域名直接转接口文档", hidden = true)
    @GetMapping("/")
    public void toDoc(HttpServletResponse response) throws IOException {
        response.sendRedirect("/doc.html");
    }
    
    @ApiOperation("新增轮播图数据")
    @PostMapping("/addBanners")
    public void putBanner(@RequestBody Banner banner){
		// ......
    }
    
    @ApiOperation("查询一个具体轮播图")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "title",value = "",required = true,example = "小白菜"),
            @ApiImplicitParam(name = "date",value = "时间",required = true,example = "2022")
    })
    @GetMapping("/searchOneBanner")
    public ROneBean<Banner> searchOneBanner(@RequestParam(name = "title",defaultValue = "") String name,
                                           @RequestParam(name = "date", defaultValue = "") String address){
        ROneBean<Banner> resp = new ROneBean<>();
        // ...
        return null
    }

    @ApiOperation("获取轮播图数据")
    @GetMapping("/getBanners")
    public RListBean<Banner> getBanners(){
        RListBean<Banner> resp = new RListBean<>();
        List<Banner> banners = iBannerService.list();
        if(banners.isEmpty()){
            resp.setCode(200);
            resp.setMsg("轮播图数据为空。");
        }else{
            resp.setCode(200);
            resp.setMsg("获取轮播图数据成功");
            resp.setData(banners);
        }
        return resp;
    }
}

六、接口文档预览

到此这篇关于SpringBoot中使用Knife4J的文章就介绍到这了,更多相关SpringBoot 使用Knife4J内容请搜索编程网以前的文章或继续浏览下面的相关文章希望大家以后多多支持编程网!

阅读原文内容投诉

免责声明:

① 本站未注明“稿件来源”的信息均来自网络整理。其文字、图片和音视频稿件的所属权归原作者所有。本站收集整理出于非商业性的教育和科研之目的,并不意味着本站赞同其观点或证实其内容的真实性。仅作为临时的测试数据,供内部测试之用。本站并未授权任何人以任何方式主动获取本站任何信息。

② 本站未注明“稿件来源”的临时测试数据将在测试完成后最终做删除处理。有问题或投稿请发送至: 邮箱/279061341@qq.com QQ/279061341

软考中级精品资料免费领

  • 历年真题答案解析
  • 备考技巧名师总结
  • 高频考点精准押题
  • 2024年上半年信息系统项目管理师第二批次真题及答案解析(完整版)

    难度     813人已做
    查看
  • 【考后总结】2024年5月26日信息系统项目管理师第2批次考情分析

    难度     354人已做
    查看
  • 【考后总结】2024年5月25日信息系统项目管理师第1批次考情分析

    难度     318人已做
    查看
  • 2024年上半年软考高项第一、二批次真题考点汇总(完整版)

    难度     435人已做
    查看
  • 2024年上半年系统架构设计师考试综合知识真题

    难度     224人已做
    查看

相关文章

发现更多好内容

猜你喜欢

AI推送时光机
位置:首页-资讯-后端开发
咦!没有更多了?去看看其它编程学习网 内容吧
首页课程
资料下载
问答资讯