SpringBoot引入Knife4j(增强版Swagger)为Java MVC框架生成api文档

本文主要是介绍SpringBoot引入Knife4j(增强版Swagger)为Java MVC框架生成api文档,希望对大家解决编程问题提供一定的参考价值,需要的开发者们随着小编来一起学习吧!

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名knife4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍!

 

快速开始

添加maven依赖

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

配置文件配置

@Configuration
@EnableSwagger2
@EnableKnife4j
public class SwaggerConfiguration {@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("2.1版本").select()// 这里指定Controller扫描包路径.apis(RequestHandlerSelectors.basePackage("com.jaemon.app.controller")).paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("app项目接口文档").description("app项目").termsOfServiceUrl("http://IP:PORT/{contextPath}/doc.html").contact(new Contact("Jaemon", "http://answer", "answer_ljm@163.com")).license("app service").licenseUrl("https://www.github.com").version("1.0").build();}
}

访问: http://IP:PORT/{contextPath}/doc.html
eg. http://localhost:8888/oms/doc.html

 

入门使用

实体类

@Data
@ApiModel("用户查询请求对象")
public class UserReqDTO {@ApiModelProperty(notes = "用户姓名")private String userName;@ApiModelProperty(notes = "登录账号")private String loginName;
}
@Data
@ApiModel("用户返回视图对象")
@AllArgsConstructor
public class UserVO {@ApiModelProperty(required = true, notes = "用户id")private Long id;@ApiModelProperty(required = true, notes = "用户姓名")private String userName;@ApiModelProperty(required = true, notes = "登录账号")private String loginName;
}
@ApiModel("通用接口返回对象")
@Data
@AllArgsConstructor
public class Result<T> {@ApiModelProperty(required = true, notes = "响应码", example = "0")private int code;@ApiModelProperty(required = true, notes = "响应描述", example = "成功")private String msg;@ApiModelProperty(notes = "响应数据")private T data;
}

控制层

@Api(value = "", tags = "测试接口")
// 大分类顺序
@ApiSort(value = 1)
@RestController
@RequestMapping(value = "/demo")
public class DemoController {@PostMapping("/userList")@ApiOperation(value = "userList接口", notes = "查询用户列表")@ApiResponses(value = {@ApiResponse(code = 0, message = "请求成功"),@ApiResponse(code = 1, message = "请求失败")})public Result userList(@RequestBody UserReqDTO userReqDTO) {List<UserVO> userVOS = Lists.newArrayList();UserVO userVO;for (int i = 0; i < 5; i++) {userVO = new UserVO((long)i, "Jaemon" + i, "Jaemon" + i);userVOS.add(userVO);}return new Result(0, "成功", userVOS);}@ApiOperation(value = "findByUserId接口", notes = "根据用户id查询用户信息")@ApiImplicitParam(name = "id", value = "用户id", paramType = "path")@GetMapping("/findByUserId/{id}")public Result<UserVO> findByUserId(@PathVariable("id") Long id) {UserVO userVO = new UserVO(id, "Jaemon", "Jaemon");return new Result(0, "成功", userVO);}}

 

常用注解说明

  • @Api: 用在类上,说明该类的作用
  • @ApiOperation: 用在方法上,说明方法的作用,标注在具体请求上,value和notes的作用差不多,都是对请求进行说明;tags则是对请求进行分类的,比如你有好几个controller,分别属于不同的功能模块,那这里我们就可以使用tags来区分了,看上去很有条理
  • @ApiImplicitParams: 用在方法上包含一组参数说明
  • @ApiImplicitParam: 用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
    • paramType:参数放在哪个地方
    • header 请求参数的获取:@RequestHeader
    • query 请求参数的获取:@RequestParam
    • path(用于restful接口) 请求参数的获取:@PathVariable
    • body(不常用)
    • form(不常用)
    • name: 参数名
    • dataType: 参数类型
    • required: 参数是否必须传
    • value: 参数的意思
    • defaultValue: 参数的默认值
  • @ApiResponses: 用于表示一组响应
  • @ApiResponse: 用在@ApiResponses中,一般用于表达一个错误的响应信息
    • code: 数字,例如400
    • message: 信息,例如”请求参数没填好”
    • response: 抛出异常的类
  • @ApiModel: 描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候)表明这是一个被swagger框架管理的model,用于class上
  • @ApiModel: 使用在实体类上,描述实体类。
  • @ApiModelProperty : 使用在实体类上的成员变量上,描述成员变量的含义。

 

SpringCloud微服务架构中使用

在Spring Cloud的微服务架构下,每个微服务其实并不需要引入前端的Ui资源,因此在每个微服务的Spring Boot项目下,引入knife4j提供的微服务starter

<dependency>    <groupId>com.github.xiaoymin</groupId>    <artifactId>knife4j-micro-spring-boot-starter</artifactId>    <version>${knife4j.version}</version>
</dependency>

在网关聚合文档服务下,可以再把前端的ui资源引入

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

 

Reference

  • knife4j
  • Swagger 增强(knife4j)自动生成Api 文档(SpringBoot & SpringCloud Gateway自动配置

这篇关于SpringBoot引入Knife4j(增强版Swagger)为Java MVC框架生成api文档的文章就介绍到这儿,希望我们推荐的文章对编程师们有所帮助!



http://www.chinasem.cn/article/1005402

相关文章

在React中引入Tailwind CSS的完整指南

《在React中引入TailwindCSS的完整指南》在现代前端开发中,使用UI库可以显著提高开发效率,TailwindCSS是一个功能类优先的CSS框架,本文将详细介绍如何在Reac... 目录前言一、Tailwind css 简介二、创建 React 项目使用 Create React App 创建项目

Java编译生成多个.class文件的原理和作用

《Java编译生成多个.class文件的原理和作用》作为一名经验丰富的开发者,在Java项目中执行编译后,可能会发现一个.java源文件有时会产生多个.class文件,从技术实现层面详细剖析这一现象... 目录一、内部类机制与.class文件生成成员内部类(常规内部类)局部内部类(方法内部类)匿名内部类二、

SpringBoot实现数据库读写分离的3种方法小结

《SpringBoot实现数据库读写分离的3种方法小结》为了提高系统的读写性能和可用性,读写分离是一种经典的数据库架构模式,在SpringBoot应用中,有多种方式可以实现数据库读写分离,本文将介绍三... 目录一、数据库读写分离概述二、方案一:基于AbstractRoutingDataSource实现动态

使用Jackson进行JSON生成与解析的新手指南

《使用Jackson进行JSON生成与解析的新手指南》这篇文章主要为大家详细介绍了如何使用Jackson进行JSON生成与解析处理,文中的示例代码讲解详细,感兴趣的小伙伴可以跟随小编一起学习一下... 目录1. 核心依赖2. 基础用法2.1 对象转 jsON(序列化)2.2 JSON 转对象(反序列化)3.

Springboot @Autowired和@Resource的区别解析

《Springboot@Autowired和@Resource的区别解析》@Resource是JDK提供的注解,只是Spring在实现上提供了这个注解的功能支持,本文给大家介绍Springboot@... 目录【一】定义【1】@Autowired【2】@Resource【二】区别【1】包含的属性不同【2】@

springboot循环依赖问题案例代码及解决办法

《springboot循环依赖问题案例代码及解决办法》在SpringBoot中,如果两个或多个Bean之间存在循环依赖(即BeanA依赖BeanB,而BeanB又依赖BeanA),会导致Spring的... 目录1. 什么是循环依赖?2. 循环依赖的场景案例3. 解决循环依赖的常见方法方法 1:使用 @La

Java枚举类实现Key-Value映射的多种实现方式

《Java枚举类实现Key-Value映射的多种实现方式》在Java开发中,枚举(Enum)是一种特殊的类,本文将详细介绍Java枚举类实现key-value映射的多种方式,有需要的小伙伴可以根据需要... 目录前言一、基础实现方式1.1 为枚举添加属性和构造方法二、http://www.cppcns.co

Elasticsearch 在 Java 中的使用教程

《Elasticsearch在Java中的使用教程》Elasticsearch是一个分布式搜索和分析引擎,基于ApacheLucene构建,能够实现实时数据的存储、搜索、和分析,它广泛应用于全文... 目录1. Elasticsearch 简介2. 环境准备2.1 安装 Elasticsearch2.2 J

使用C#代码在PDF文档中添加、删除和替换图片

《使用C#代码在PDF文档中添加、删除和替换图片》在当今数字化文档处理场景中,动态操作PDF文档中的图像已成为企业级应用开发的核心需求之一,本文将介绍如何在.NET平台使用C#代码在PDF文档中添加、... 目录引言用C#添加图片到PDF文档用C#删除PDF文档中的图片用C#替换PDF文档中的图片引言在当

详解C#如何提取PDF文档中的图片

《详解C#如何提取PDF文档中的图片》提取图片可以将这些图像资源进行单独保存,方便后续在不同的项目中使用,下面我们就来看看如何使用C#通过代码从PDF文档中提取图片吧... 当 PDF 文件中包含有价值的图片,如艺术画作、设计素材、报告图表等,提取图片可以将这些图像资源进行单独保存,方便后续在不同的项目中使