java中如何使用Swagger工具生成在线接口文档
前言
Swagger
是由美国软件公司SmartBear Software开发的一种用于描述和定义RESTful API的工具。目前,Swagger已经成为了API开发和管理领域中最流行的工具之一,被广泛应用于各种软件开发项目中。
一、Swagger、Knife4j是什么?
· Swagger是一种用于描述和定义RESTful API的工具和规范。它可以让开发人员更加方便地描述API的请求和响应结构、参数、错误码等信息,同时也能够生成交互式的API文档和客户端代码。通过使用Swagger,开发人员可以更加规范和标准化地设计和管理API,从而提高API的可读性、可维护性和可测试性。
· Knife4j是为 java MVC 框架集成Swagger生成API文档的增强解决方案
二、java中如何使用Knife4j
1.在pom.xml文件中引入knife4j的maven坐标
代码如下:
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.2</version>
</dependency>
2.配置类中加入knife4j的相关配置
代码如下:
@Configuration
@Slf4j
public class WebMvcConfiguration extends WebMvcConfigurationSupport {
@Bean
public Docket docket() {
log.info("准备生成接口文档...");
ApiInfo apiInfo = new ApiInfoBuilder()
.title("项目接口文档")
.version("2.0")
.description("项目接口文档")
.build();
Docket docket = new Docket(DocumentationType.SWAGGER_2)
.groupName("api")
.apiInfo(apiInfo)
.select()
.apis(RequestHandlerSelectors.basePackage("com.sky.controller.admin"))
.paths(PathSelectors.any())
.build();
return docket;
}
}
· 此处创建的 WebMvcConfiguration类 继承自 WebMvcConfigurationSupport 是SpringMVC提供的扩展类,用于提供拦截器、资源处理器等注册功能。
· 在声明的 docket 方法上加上 @bean 注解,此时由spring框架创建 Docket 对象并由 spring框架管理
· 创建ApiInfo对象,对象中的属性title、version、description为自定义的基本信息
· 创建Docket对象,此时对象中的属性groupName、apiInfo设置接口文档信息,已经创建好apiInfo对象直接调用,默认调用方法select 最重要的是apis方法(指定生成接口文档需要扫描的包,当下我扫描的是controller层下的admin)paths固定写法
3.设置静态资源映射
@Configuration
@Slf4j
public class WebMvcConfiguration extends WebMvcConfigurationSupport {
@Bean
public Docket docket() {
log.info("准备生成接口文档...");
ApiInfo apiInfo = new ApiInfoBuilder()
.title("项目接口文档")
.version("2.0")
.description("项目接口文档")
.build();
Docket docket = new Docket(DocumentationType.SWAGGER_2)
.groupName("api")
.apiInfo(apiInfo)
.select()
.apis(RequestHandlerSelectors.basePackage("com.sky.controller.admin"))
.paths(PathSelectors.any())
.build();
return docket;
}
/**
* 设置静态资源映射
* @param registry
*/
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
log.info("开始设置静态资源映射...");
registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
· 设置静态资源映射,否则接口文档页面无法显示
· 通过重写 WebMvcConfigurationSupport 父类中的 addResourceHandlers 方法 将我们的/doc.html 和 /webjars/**路径请求映射到类路径下的固定路径中,也就是说生成的接口文档都会放到这些路径中。
4.项目实战
· Swagger常用注解@Api( tags = " " ) 和 @ApiOperation( " " )
· 注解@Api( tags = " " )放在Controller类的上方,@ApiOperation( " " )则放在方法的上方
总结
Swagger是在开发阶段使用到的框架,目的是为了帮助后端开发人员做后端的接口测试
· 使用Swagger注解可以使接口文档有更高的可读性。最常使用的@Api( tags = " " ) 和 @ApiOperation( " " )