Swaggerj使用教程
简介Swagger是个非常强大的API文档工具，它们可以帮助开发人员快速创建和管理API文档，并提供了丰富的功能和可视化界面。本文将为您介绍Swagger和Knife4j的使用教程，帮助您更好地了解和使用它们。
什么是Swagger？这里是Swagger的官网:Swagger官网
Swagger是一个用于设计、构建、文档化和使用RESTful风格的Web服务的开源软件框架。它提供了一种简单而强大的方式来描述和访问API的功能，使得开发人员可以更轻松地构建和测试API。
Swagger的主要功能包括：
API文档自动生成：Swagger可以根据代码注释自动生成API文档，包括API的路径、参数、请求和响应的格式等信息。
可视化界面：Swagger提供了一个可视化的界面，使开发人员可以直观地查看和测试API。
API测试工具：Swagger提供了一个内置的API测试工具，可以直接在文档中进行API的测试和调试。
API验证：Swagger可以验证API的请求和响应的格式是否符合定义的规范。
Swagger的安装和配置要使用Swagger，您需要将Swagger的库添加到您的项目中，并进行相应的配置。
添加Swagger库：在Maven项目中，您可以在pom.xml文件中添加以下依赖：代码语言：javascript代码运行次数：0运行复制
配置Swagger：在您的Spring Boot应用程序中，您需要创建一个配置类来启用Swagger和配置相关的参数。以下是一个示例配置类：代码语言：javascript代码运行次数：0运行复制@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.api"))
.paths(PathSelectors.any())
.build();
}
}在上述配置中，您需要指定API的包路径和URL路径的匹配规则。
启动应用程序：完成上述配置后，您可以启动您的应用程序，并访问http://localhost:8080/swagger-ui.html来查看生成的API文档。实践文章中的项目在这个gitee仓库中:博客中的代码
Springboot集成Swagger开启Swagger
代码语言：javascript代码运行次数：0运行复制@Configuration
@EnableWebMvc
@EnableSwagger2 // 开启Swagger2
public class SwaggerConfig implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/**").addResourceLocations(
"classpath:/static/");
registry.addResourceHandler("swagger-ui.html").addResourceLocations(
"classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations(
"classpath:/META-INF/resources/webjars/");
WebMvcConfigurer.super.addResourceHandlers(registry);
}
}配置好了之后，就可以启动了。
我配置的端口号是8080，然后打开这个地址就可以进入Swagger的页面：http://localhost:8080/swagger-ui.html
配置Swagger信息Swagger的bean实例Docket这是Swagger中的Docket的各项参数
groupName(String)：指定API文档的分组名称。可以使用多个Docket实例来创建多个API文档分组，每个分组可以有不同的配置。
select()：返回一个ApiSelectorBuilder对象，用于定义哪些接口和路径应该包含在生成的文档中。
apis(Predicate)：用于筛选包含在文档中的接口。可以使用RequestHandlerSelectors类提供的一些静态方法来定义筛选规则，例如basePackage()、any()、none()等。
paths(Predicate)：用于筛选包含在文档中的路径。可以使用PathSelectors类提供的一些静态方法来定义筛选规则，例如ant()、regex()等。
apiInfo(ApiInfo)：用于设置API文档的基本信息，包括标题、描述、版本号、联系人信息等。
title(String)：设置API文档的标题。
description(String)：设置API文档的描述。
version(String)：设置API文档的版本号。
termsOfServiceUrl(String)：设置API文档的服务条款URL。
license(License)：设置API文档的许可证信息，包括名称和URL。
contact(Contact)：设置API文档的联系人信息，包括姓名、邮箱、网址等。
protocols(Set)：设置API文档支持的协议。可以使用字符串集合指定多个协议，例如"http"、"https"等。
host(String)：设置API文档的主机名。可以指定完整的主机名，例如"www.example.com"，或者只指定域名部分。
pathMapping(String)：设置API文档的基础路径。可以指定一个路径前缀，用于对所有路径进行统一的处理。
enable(boolean)：设置是否启用Swagger文档生成。默认情况下，Swagger文档生成是启用的。
ignoredParameterTypes(Class…)：设置要忽略的参数类型。在生成API文档时，将忽略指定类型的参数。
globalOperationParameters(List)：设置全局的操作参数。这些参数将应用于所有的API操作。
additionalModels(Class…)：设置额外的模型类。这些模型类将被包含在生成的API文档中。
代码语言：javascript代码运行次数：0运行复制@Configuration
@EnableWebMvc
@EnableSwagger2 // 开启Swagger2
public class SwaggerConfig implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/**").addResourceLocations(
"classpath:/static/");
registry.addResourceHandler("swagger-ui.html").addResourceLocations(
"classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations(
"classpath:/META-INF/resources/webjars/");
WebMvcConfigurer.super.addResourceHandlers(registry);
}
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
}
// 配置Swagger信息=apiInfo
private ApiInfo apiInfo(){
// 作者的信息
Contact contact = new Contact("极客李华", "https://blog.csdn.net/qq_51447496?spm=1011.2415.3001.5343", "1369990609@qq.com");
return new ApiInfo("极客李华的SwaggerAPI文档",
"Wonder OF U",
"V1.0",
"https://blog.csdn.net/qq_51447496?spm=1011.2415.3001.5343",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0.html",
new ArrayList());
}
}这个时候，这里的信息就发生了改变
配置扫描接口与开关代码语言：javascript代码运行次数：0运行复制@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// RequestHandlerSelectors 配置要扫描接口的方式
// basePackage
// any() 扫描全部
// none() 不扫描
// withClassAnnotation 扫描类上的注解，参数是一个注解的反射对象
// withMethodAnnotation 扫描方法上的注解，参数是一个注解的反射对象
.apis(RequestHandlerSelectors.basePackage("com.example.swaggerdemo.controller"))
// paths() 过滤什么路径
.paths(PathSelectors.ant("/user/**")) // 允许/user/下面所有的
.build();
}在上面的配置中，我们只允许user下面的包，这个时候，我们的接口文档里面就只有usercontroller了
分组也接口注释配置API分组.groupName("极客李华")
配置多个分组
代码语言：javascript代码运行次数：0运行复制@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("极客李华")
.enable(true) // enable是否启动Swagger,如果为False 则无法访问Swagger
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.swaggerdemo.controller"))
.build();
}
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("B");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("C");
}现在就有了多个分组，可以看出来，每个分组的内容都不相同
接口注释简介在Swagger中，有一些用于定义API文档的注解和语法，包括@ApiModel、@ApiModelProperty、@ApiParam等。下面是对这些注解和语法的详细介绍：
@ApiModel：用于对数据模型进行注解，定义在类上。可以用来描述请求或响应中的数据模型。常用的属性有：
value：指定数据模型的名称。
description：指定数据模型的描述。
parent：指定数据模型的父类。
discriminator：指定数据模型的鉴别器属性。
@ApiModelProperty：用于对数据模型的属性进行注解，定义在类的字段或方法上。可以用来描述属性的名称、类型、描述等信息。常用的属性有：
value：指定属性的名称。
dataType：指定属性的数据类型。
required：指定属性是否必填。
example：指定属性的示例值。
notes：指定属性的描述。
hidden：指定属性是否在文档中隐藏。
@ApiParam：用于对方法的参数进行注解，定义在方法的参数上。可以用来描述参数的名称、类型、描述等信息。常用的属性有：
value：指定参数的名称。
required：指定参数是否必填。
defaultValue：指定参数的默认值。
allowableValues：指定参数的可选值范围。
allowMultiple：指定参数是否允许多个值。
access：指定参数的访问权限。
@ApiOperation：用于对API操作进行注解，定义在方法上。可以用来描述API操作的名称、描述、请求方法等信息。常用的属性有：
value：指定API操作的名称。
notes：指定API操作的描述。
httpMethod：指定API操作的请求方法。
response：指定API操作的响应类型。
consumes：指定API操作接受的媒体类型。
produces：指定API操作返回的媒体类型。
responseContainer：指定API操作的响应容器类型。
ApiModel和ApiModelProperty
这里面加上了对应的注释
ApiOperation和Api在这里插入图片描述接口测试Swagger也是可以进行接口测试的