一、背景介绍
1.1、Swagger介绍
Swagger是一个开源的规范和工具集,用于设计、构建和文档化 RESTful API。它提供了一种简单易懂的方式来描述API的结构、请求和响应参数以及其它相关信息。通过使用Swagger,开发人员可以更加轻松地设计和开发API,并生成交互式文档,使得API的使用者能够快速了解和调用API。
1.2、Swagger主要功能和用途:
- API设计:Swagger允许开发人员使用简洁的语法定义API的接口、参数、数据模型等信息,提供了一种标准化的方式来描述API的结构。
- 自动化文档生成:Swagger可以根据API定义自动生成交互式文档,包括API的终端点、参数、请求示例、响应示例等,方便开发人员和用户查阅和理解API的用法。
- 客户端代码生成:Swagger可以根据API定义生成客户端代码,支持多种编程语言和平台,简化客户端与API的交互过程。
- API测试:Swagger可以通过交互式文档提供API的测试界面,方便开发人员进行接口测试和调试。
- API管理:Swagger可以集成到API管理平台中,提供API的注册、发布、监控和权限控制等功能,方便对API进行管理和维护。
二、创建项目
三、配置Swagger信息
在pom文件下添加对应的maven包
<!--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>
接着编写Swagger配置类
然后启动项目,访问链接http://localhost:8080/swagger-ui.html
这里有的在springboot版本大于2.6.1的时候会出现空指针报错
Failed to start bean 'documentationPluginsBootstrapper';
nested exception is java.lang.NullPointerException
解决方法有两个,一是降低springboot版本,二是添加两个配置文件
降低springboot版本这里不做介绍,介绍的是添加配置文件解决方法
首先在启动类中添加@EnableWebMvc注解
接着添加一个配置文件
@Configuration
public class WebMVCConfig implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
/**
* 配置swagger-ui显示文档
*/
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
这样就能解决空指针报错了
四、更改文档信息:
在swagger配置类里面写docket的方法
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
//作者信息
Contact contact = new Contact("小俞", "", "");
return new ApiInfo("小俞的swaggerApi文档",
"这个是一个描述",
"1.0版本号",
"地址",
contact, "Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
重启项目之后,文件的信息就会进行更改:
五、配置扫描路径
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
.select()
// RequestHandlerselectors.配罩要扫播接口的方式
// basePackage("com.example.demo3"):指定要扫描的包
// any ():扫描全部
//none():个扫描
//withclassAnnotation,扫描类上的注解,参数足一个注解的反射对象 withClassAnnotation(RestController.class) 扫描类上有RestController注解的类
// withMethodAnnotation:扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("com.example.demo3"))
//过滤路径 ant("/code/**")只扫描带有code的路径的注解
//.paths(PathSelectors.ant("/code/**"))
.build();
}
扫描的路径一定要在select和build两个方法里面,这样才能定义到
六、配置使用范围
swagger如果在项目发布的时候,还能访问,这样我们就会有接口暴露的风险,所以这里我们就可以配置在特定的情况下,无法使用swagger
这里我们使用多个配置文件
其他三个包配置的仅是端口不一致即可,这样我们就可以在配置文件中,获取当前项目的一个发布情况
这样即可,后续如果说我们项目发布了,就可以把配置文件里面的信息进行对应的更改即可。
七、自定义组名
自定义组名只需要通过内置的groupName即可
效果如下:
八、配置多个分组
我们做一个项目的时候肯定是进行一个团队的开发形式,所以为了管理自己的接口,我们有必要的就是进行多个组的管理,多个组的形式就是创建多个bean实例即可:
@Bean
public Docket docket1() {
return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}
@Bean
public Docket docket2() {
return new Docket(DocumentationType.SWAGGER_2).groupName("A1");
}
@Bean
public Docket docket3() {
return new Docket(DocumentationType.SWAGGER_2).groupName("A2");
}
效果如下:
九、一些常用的注解
在上面的操作过程中,我们发现接口的一些信息都是英文的,不利于测试人员的阅读,所以我们为了增加接口文档的可读性,会使用一些注解,来达到这样的目的:
Swagger常用的注解分为两类:API注解和Model注解。
API注解:
- @Api:用于描述整个Controller或者某个接口的信息。
- @ApiOperation:用于描述接口的操作,包括接口名称、接口描述、请求方式、请求URL、请求参数、响应结果等。
- @ApiParam:用于描述接口中的参数信息,包括参数名称、参数描述、是否必填等。
- @ApiImplicitParam:用于描述接口中的参数信息,与@ApiParam类似,但更加灵活,可以支持更多的参数类型和传递方式。
- @ApiModel:用于描述数据模型(DTO),包括模型名称、描述、属性等。
- @ApiModelProperty:用于描述数据模型中的属性,包括属性名称、描述、数据类型、是否必填等。
Model注解:
- @ApiModel:用于描述数据模型(DTO),包括模型名称、描述、属性等。
- @ApiModelProperty:用于描述数据模型中的属性,包括属性名称、描述、数据类型、是否必填等。
下面展示常用的3个注解:
这里需要注意的是返回值存在实体类,该实体类才会被swagger扫描到!!!!!!
以上就是swagger介绍的全部内容。
注意在项目发布的时候需要更改项目的一个上线情况。