当前位置：首页 > news >正文

Java的Mvc整合Swagger的knife4框架

news 来源：原创 2025/7/13 9:51:09

Swagger的介绍

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。使用Swagger，就是把相关的信息存储在它定义的描述文件里面（yml或json格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。而Springfox-swagger,则可以通过扫描代码去生成这个描述文件，连描述文件都不需要再去维护了。所有的信息，都在代码里面了。代码即接口文档，接口文档即代码。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

swagger的主要作用

Swagger最主要的作用就是接口文档的在线自动生成和功能测试，也就是测试我们开发的功能是否可用。

Swagger的使用

如果直接使用Swagger是非常麻烦的，应为需要使用Swagger其实就是在编写一个json文件，这个是十分的繁琐的一道过程。所以一般是使用的java的mvc集成Swagger的框架增强的解决方案knife4它的底层是由Swagger组成的但是使用起来是相对比较简单的。

1.导入依赖

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

2.导入knife4相关的配置类

@EnableSwagger2
@EnableKnife4j//与上面的注解表示开启了Swagger文档功能
@Configuration//声明为配置类
public class WebMvcConfig extends WebMvcConfigurationSupport {//mvc静态资源的映射类
//创建api接收文档
@Bean
public Docket createRestApi(){return  new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("你的controller包在项目中的位置")).paths(PathSelectors.any()).build();
}

//api的接口文档的模板
private ApiInfo apiInfo(){return new ApiInfoBuilder().title("标题").version("版本号").description("描述的信息").build();}
}

上面第一个方法的返回值docket是文档的意思，通过这个对象来具体描述文档的信息，需要注意.apis(RequestHandlerSelectors.basePackage())这里面需要项目中的controller的包的位置，因为前段发送请求是发送进入的controller中的某个方法上面，所以需要来扫描每一个方法，最终映射成一个接口。然让其生成出对于的接口文档

3.设置静态资源的映射

设置这个的原因是需要让接口文档页面可以被访问。

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");}

doc.html这个页面并不需要我们自己写，而是有框架帮助我们自动生成的。

4.在你的拦截器设置不需要进行处理的路径

配置好后需要在你的拦截器上面对于接口文档的路径。

"/doc.html",
"/webjars/",
"/swagger-resources",
"/v2/api-docs"

如果并不想要设计的话，可以先进行登录之后可以直接进行访问。

Swagger效果展示

添加后成功的效果如图显示

我们可以从上获取到诸多信息，如作版本、host、basePaht、分租Url等信息。这些信息都是我们之前添加在kinfe4中的apiInfo方法中所设置的信息。我们可以看到所统计的接口信息，比如post、put、delete、get等接口d的数量

具体可以看我们的左侧的信息展示，可以清晰的看见我们每一个的controller类里面的接口具体有多少个，可以非常清晰的展示在我们页面上。

我们选择一个点开看可以将我们每一个方法的方法名和请求类型都展示在页面上给我吗后端开发人员进行查看。

我们选择一个方法点开查看，可以清晰的看见我们该方法的参数名称和我们该参数的类型，比如我们参数的请求示例、响应数据类型等信息。我们的参数在下面也可以获取到这个参数是否是必须需要的。

继续往下翻找可以看的这个方法的响应状态、响应参数、响应示例等信息。我们可以从响应示例看出我们的具体响应是什么样子的方便我们使用。

我们点击调用可以看见我们的请求所需要的参数，可以进行输入参数也可以点击发送，也可以直接点击发送。

这里可以看见我们的请求已经返回了，这里是已经登陆的情况，如果并没有登录会在msg里面返回一个NOTLOGIN。

我们不仅可以通过knife4自动生成接口文档，给我们后端开发人员使用来进行测试，还有可以将我们这个生成的文档导出。

我们点击这个文档管理下面的离线文档，可以在右侧显示中看见它为我们提供了4种下载方式Html、Markdown、Word、OpenAPI。

我们选择Markdown下载模式可以看见它已经为我们下载好了。我们点开刚刚下载好的文档查看。

可以看见我们已经是提供好了我们整个项目的api文档，如果你选择的是Openapi的下载方式那么下载出的格式是json类型。

在左侧的Swagger Models里面有着我们整个项目的数据模型模型，每一个类点开之后属性都会展示出来，给我们可以快速且方便的查询。

Swagger的常用注解

1.@Api

这个主要用在请求类，例如Controller，表示对于类的说明。

使用方式：@Api(value = "/user", description = "Operations about user")

它表示数据是user类型的，

value：这是类的路径，将在生成的 Swagger 文档中显示。
description：这是对数据来源的描述，也将在生成的 Swagger 文档中显示

2.@ApiModel

通常使用在实体类上，表示返回响应数据的信息。

@ApiModel(value = "UserModel", description = "A model representing a user")

这个表示来自于user类，它提供了两个属性

value：这是模型的名称，将在生成的 Swagger 文档中显示。
description：这是对模型的描述，也将在生成的 Swagger 文档中显示

3.@ApiModelProperty

这个注解则用于类中的字段，并为它们提供了额外的元数据，如字段的描述和是否必需等。通过使用这些注解，你可以更容易地为你的 RESTful Web 服务生成和维护 API 文档，它的属性有：

value：字段说明 name：重写属性名字 dataType：重写属性类型 required：是否必填（true为必填） example：举例说明 hidden：隐藏（true为隐藏）

例如: @ApiModelProperty(value = "值",required = true/false,name="属性名",example="说明")

4.‌@ApiOperation

主要使用于方法表示一个http请求的操作，方法如下：

@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”）

value：对该操作进行简单的描述，尽量控制在120字符以内。 notes：对操作的详细描述。 httpMethod：指定操作使用的HTTP方法类型，可选值 “GET”、“HEAD”、“POST”、“PUT”、“DELETE”、“OPTIONS”和“PATCH”。 tags：用来给操作打标签，Swagger UI 将在操作列表下面展示 tag 列表，每个 tag 下面展示拥有该 tag 的操作列表。（就是分组）

5.‌@ApiImplicitParam

作用在方法上，表示单独的请求参数它的属性有：

1.name ：参数名。

2.value ：参数的具体意义，作用。

3.required ：参数是否必填。

4.dataType ：参数的数据类型。

5.paramType ：查询参数类型，这里有几种形式

类型的作用：

path 以地址的形式提交数据 query 直接跟参数完成自动映射赋值 body 以流的形式提交仅支持POST header 参数在request headers 里边提交 form 以form表单的形式提交仅支持POST

6.‌@ApiImplicitParams

使用在请求方法上面，表示接受多个@ApiImplicitParam参数

Swagger常用接口的使用

1.@ApiModel和@ApiModelProperty的用法

选择一个实体类使用上面的@ApiModel和@ApiModelProperty注解，运行后在doc.html里面查看我们的结果。

可以清晰看到的看见我们之前的setmeal类已经改名为套餐，也就是我们在@APIModel里面设置的名称，并且点开这个类已经可以看的我们的属性里面有说明，它的话是我们在@ApiModelProperty里面设置的说明。

2.@Api和@ApiOperation的用法

将我们的上面的@Api和@ApiOperation添加到我们的controller也就是请求方法上面。保存进行运行再次到doc.html里面查看我们这个controller类有什么变化。

可以看见我们doc.html页面上的左侧已经进行了更新，上面显示的接口名不再是类名而是我们在@Api里面输入的名称，并且方法名也是我们在@ApiOperation里面所输入的名称。

3.@ApiImplicitParam和@ApiImplicitParams的用法

我们使用了ApiImplicitParams将多个ApiImplicitParam包裹起来，每一个ApiImplicitParam里面都是我们方法所需要的一个参数，并标明其名称和意义以及是否是必须要传递的参数等信息

已经可以看到我们的参数的一些说明和信息，也就是我们在ApiImplicitParam所包含的参数里面给其添加的信息，这也更加方便我们开发时对于项目的检查和理解。