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文件中添加以下依赖：
<!--引入swagger--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.swagger</groupId> <artifactId>swagger-annotations</artifactId> <version>1.5.22</version> </dependency> <dependency> <groupId>io.swagger</groupId> <artifactId>swagger-models</artifactId> <version>1.5.22</version> </dependency>
- 配置Swagger：在您的Spring Boot应用程序中，您需要创建一个配置类来启用Swagger和配置相关的参数。以下是一个示例配置类：
@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
@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文档中。
@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()); } }
这个时候，这里的信息就发生了改变
配置扫描接口与开关
@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("极客李华")
- 配置多个分组
@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也是可以进行接口测试的
