文章目录
Swagger2使用说明
1、swagger2作用
接口管理工具,是一套规范项目接口,帮接口自动生成接口文档。方便各个系统之间的调用,方便各方系统。
提供ui界面,方便开发人员进行测试,节省开发人员大部分的时间。
2、spring 集成swagger2
2.1 引用 springfox 包
<!-- swagger的依赖-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
2.2 涉及到的实体类以及controller
Customer.java 实体类
@Data
@AllArgsConstructor
@NoArgsConstructor
@ToString
public class Customer {
private String name;
private String password;
}
CustomerController.java Customer相关的Controller类
@RestController
@Slf4j
public class CustomerController {
@GetMapping("/login")
public String login(String name,String password ){
return "Hello " + name +"||| " + password;
}
}
2.3 启动类中添加注解
启动类中添加注解@EnableSwagger2
表明整个SpringBoot工程中启用Swagger2,此时就已经可以在浏览器中输入http://localhost:8080/swagger-ui.html访问简易的页面(具体的需要进行配置类的定义)
SpringApplication.java中
@SpringBootApplication
@EnableSwagger2
public class SwaggerApplication {
public static void main(String[] args) {
SpringApplication.run(SwaggerApplication.class, args);
}
}
swagger-ui页面展示
图片可以看到很多地方都是默认的英文,这时候需要添加配置类,让接口说明看的很通俗、直观
3、Swagger2的配置
3.1 编写Swagger2 配置类
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
/**
* @PROJECT_NAME: spring-swagger
* @DESCRIPTION:
* @USER: NORTHKING
* @DATE: 2020/10/22 20:21
*/
@Configuration
public class SwaggerConfig {
@Bean
public Docket getDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(swaggerDemoApiInfo())
.select().build();
}
private ApiInfo swaggerDemoApiInfo() {
return new ApiInfoBuilder()
.contact(new Contact("nick,sky", "www.baidu.com", "nick.sky@163.com"))
// 标题
.title("这是测试Swagger的标题")
// 描述
.description("这是测试Swagger的描述")
// 版本
.version("1.0.0")
.build();
}
}
Docket:摘要对象,通过对象配置描述文件的信息。 apiInfo:设置描述文件中 info。参数类型 ApiInfo
select():返回 ApiSelectorBuilder 对象,通过对象调用 build()可以 创建 Docket 对象
ApiInfoBuilder:ApiInfo 构建器
访问url: http://localhost:8081/swagger-ui.html现在的界面是这个样子
3.2 设置扫描的包
在swagger配置文件中没有配置扫描包,那么就会把整个工程中所有的接口扫描到并写入swagger-ui页面中
@Bean
public Docket getDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(swaggerDemoApiInfo())
.select()
// .apis(RequestHandlerSelectors.basePackage("com.nicksky.swagger.controller")) //设置扫描的包
.build();
}
对应的swagger-ui.html页面如下
设置了扫描包的配置,则不会扫描到其他包的接口
@Bean
public Docket getDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(swaggerDemoApiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.nicksky.swagger.controller")) //设置扫描的包
.build();
}
设置时候对应的swagger-ui.html页面如下
3.3 设置自定义接口配置
自定义注解,用于方法之上,标注扫描该方法
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* @PROJECT_NAME: spring-swagger
* @DESCRIPTION: swagger不扫描注解
* @USER: NORTHKING
* @DATE: 2020/10/22 21:06
*/
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface NoSwaggerAnnotion {
}
在swaggerConfig,java设置不扫描的方法
@NoSwaggerAnnotion
@PostMapping("/test")
public String test(){
return "这是controller中的test方法";
}
config中添加不扫描注解
//设置包内不扫描的方法
.apis(not(withMethodAnnotation(NoSwaggerAnnotion.class)))
这是不添加注解的swagger-ui.html扫描出的接口
这是添加@NoSwaggerAnnotion
注解之后的swagger-ui.html的接口
3.4 设置接口扫描范围
添加配置,是swagger扫描只扫描某些特定的接口,可以使用正则表达式
@Configuration
public class SwaggerConfig {
@Bean
public Docket getDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(swaggerDemoApiInfo())
.select()
//设置扫描接口所在的包
.apis(RequestHandlerSelectors.basePackage("com.nicksky.swagger.controller"))
//设置包内不扫描的方法
.apis(not(withMethodAnnotation(NoSwaggerAnnotion.class)))
//设置所有的接口都可以被扫描到
// .paths(PathSelectors.any())
//设置以某些特定要求的接口才可以被收扫描到
.paths(remotePath())
.build();
}
private Predicate<String> remotePath() {
return (regex("/login.*"));
}
在controller中添加测试方法,添加注解的方法仍然不能被扫描到
@GetMapping("/login/second")
public String login1(String name,String password ){
return "Hello1 " + name +"||| " + password;
}
@GetMapping("/first")
public String sss(String name,String password ){
return "Hellosss " + name +"||| " + password;
}
在没有配置.paths(remotePath())之前的swagger-ui.html界面是
配置之后是
由此可见,我们可以设置注解来制定不扫描方法,也可以指定扫描执行的路径的方法。可以指定扫描的包以及扫描多个包,灵活性很高
4、常用的注解
4.1 @Api
@Api
是用在类上的注解,来描述类的作用 tags:类的名称 可以有多个值 多个值表示多个副本,description:描述
@Api(tags = "这是customer相关的接口",description = "customer类接口")
public class CustomerController {···}
4.2 @ApiOperation
@ApiOperation
是用在方法上的注解,对方法进行提示信息 value:接口描述 notes:提示信息
@GetMapping("/login")
@ApiOperation(value = "登录接口",notes = "输入用户名和密码")
public String login(String name,String password ){
return "Hello " + name +"||| " + password;
}
4.3 @ApiParam
@ApiParam
是使用在方法中的参数上,用来提示改参数的信息,是否必须等 value:信息描述 name:字段名称
require:是否必须
使用@ApiParam时,必须使用@RequestParam
注解,否则获取不到值。(不适用会默认是一个body,使用之后是query类型)
@GetMapping("/login")
@ApiOperation(value = "登录接口",notes = "输入用户名和密码")
public String login(@ApiParam(value = "用户名",required = true,name = "name") @RequestParam String name, @ApiParam(value = "用户名密码",required = true,name = "password") @RequestParam String password ){
return "Hello " + name +"||| " + password;
}
这是不使用之前,最终的结果就是获取不到值
这是使用@RequestParam之后的结果
4.4 @ApiModel
@ApiModel
是使用在类上的注解,一般用在实体类上,用于描述实体类的作用 value:名称 description:描述
@Data
@AllArgsConstructor
@NoArgsConstructor
@ToString
@ApiModel(value = "用户实体类",description = "用户")
public class Customer {
private String name;
private String password;
}
对应的contrller 方法中必须是含有该对象
@GetMapping("/login/second")
public String login1(@RequestBody Customer customer ){
return "Hello1 " + customer.getName() +"||| " + customer.getPassword();
}
4.5 @ApiModelProperty
@ApiModelProperty
是使用在实体类的参数或者方法上,用来描述其含义。
value:描述,name:重写属性名,required:是否是必须的,example:示例内容,hidden:是否隐藏。
@ApiModel(value = "用户实体类",description = "用户描述")
public class Customer {
@ApiModelProperty(value = "customer实体的用户名",required = true,name = "customer.name",notes = "用户",dataType = "String")
private String name;
@ApiModelProperty(value = "customer实体的密码",required = true,name = "customer.password",notes = "密码",dataType = "String")
private String password;
}
4.6 @ApiImplicitParams
一般@ApiImplicitParams是和@ApiImplicitParam一起用,具体格式为:
@ApiImplicitParams({
@ApiImplicitParam(name = "name",value = "用户名称",dataType = "String",paramType = "query"),
@ApiImplicitParam(name = "password",value = "用户密码",dataType = "String",paramType = "query")}
)
4.7 @ApiImplicitParam
name–参数ming
value–参数说明
dataType–数据类型
paramType–参数类型 一定要加,否则会默认类型为body,获取不到值
example–举例说明
@ApiImplicitParams({
@ApiImplicitParam(name = “name”,value = “用户名称”,dataType = “String”),
@ApiImplicitParam(name = “password”,value = “用户密码”,dataType = “String”)}
)
public String test1(String name, String password){
log.info(“name:” + name + " password: " + password);
return “name:” + name + " password: " + password;
}