Springboot集成Knife4j加强的swagger配置
小知识
: Swagger是一个开放源代码软件框架,由大型工具生态系统支持,可帮助开发人员设计,构建,记录和使用RESTful Web服务。提供了UI界面,既展示接口信息,又提供了参数校验,测试功能。形成了文档规范,支持不同的语言提供丰富的组件,通过代码和注释自动生成文档。
一、导入swagger依赖
选择合适的版本,并且要注意swagegr3的版本和knife4j的版本是否匹配
<properties>
<!--选择合适的版本(最新版)-->
<swagegr.version>3.0.0</swagegr.version>
<knife4j.version>3.0.3</knife4j.version>
</properties>
<!--Swaager3-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<!-- &{}进行选择上面定义的版本值,方便后期维护修改-->
<version>${swagegr.version}</version>
</dependency>
<!--Swaager 增强knife4j-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<!--在引用时请在maven中央仓库搜索3.X最新版本号-->
<version>${knife4j.version}</version>
</dependency>
注意:此时可以进行重启Springboot项目,看是否能正常显示Swagger页面(未配置,显示Swagger的默认配置)
访问地址:http://IP:Port/doc.html#/home
结果
:
显示如上结果则证明,Swagger集成成功
二、Swagger配置文件
小提示:在Springboot中一般的配置文件,专门建一个config的文件夹,将所有需要配置的文件放入该文件夹中!!!
1、创建swagger的配置文件,放入config的文件中
命名:SwaggerConfig.java
2、进行配置文件编写
编写代码如下:
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
/**
* swagger
*
* @author xiaoguo
*/
@Configuration
@EnableKnife4j
public class SwaggerConfig {
@Bean(value = "实例化对象名称")
public Docket defaultApi2() {
return new Docket(DocumentationType.OAS_30)
.apiInfo(groupApiInfo())
.groupName("分组名称")
.select()
.apis(RequestHandlerSelectors.basePackage("扫描报的名称"))
.paths(PathSelectors.any())
.build();
}
/**
* 作者信息
*
* @return
*/
private ApiInfo groupApiInfo() {
return new ApiInfoBuilder()
.title("显示的title名称")
.description("<div style='font-size:14px;color:red;'>简介描述APIS</div>")
.termsOfServiceUrl("提供服务的服务商官网")
.version("版本")
.build();
}
}
注意:上述配置为最基本的配置,如需其他配置,查看swagger的配置手册,里面有详细的配置
三、测试是否配置生效
1、重启程序,等待重启成功
2、输入Swagger访问网址
地址:http://IP:Port/doc.html#/home
3、结果
看到如下结果则证明配置成功
四、Swagger常用注解
@Api
@Api 注解用于标注一个Controller(Class)。在默认情况下,Swagger-Core只会扫描解析具有@Api注解的类,而会自动忽略其他类别资源(JAX-RS endpoints,Servlets等等)的注解。
属性:
代码:
@RestController
@Slf4j
@RequestMapping("/user")
@Api(tags = "人员信息 API", description = "提供人员信息相关的 Rest API")
public class UserController {
@ApiOperation
@ApiOperation 注解在用于对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。
主要属性:
@ApiParam
@ApiParam作用于请求方法上,定义api参数的注解
主要属性:
代码示例:
public Result<User> getUserById(
@ApiParam(value = "ID 不为空", allowableValues = "range[1,10]", required = true)
@PathVariable("UserId") Long userId)
@ApiImplicitParams、@ApiImplicitParam
(1)、@ApiImplicitParams:用在请求的方法上,包含一组参数说明
(2)、@ApiImplicitParam:对单个参数的说明
@ApiImplicitParams({
//参数效验
@ApiImplicitParam(name="phonenum",value="手机号",required=true,paramType="form"),
@ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
@ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
})
@GetMapping("/login")
public ApiResult login(@RequestParam String mobile, @RequestParam String password,
@RequestParam Integer age){
//...
return JsonResult.ok(map);
@ApiModel、@ApiModelProperty
@ApiModel用于描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候)。
@ApiModelProperty用来描述一个Model的属性
使用场景
**@ApiModel**** 用在模型类上,对模型类作注解
**@ApiModelProperty**** 用在属性上,对属性作注解
代码示例:
@Data
@ApiModel(description= "返回人员信息")
public class UserQueryVo extends BaseEntity{
@ApiModelProperty(value = "主键", required = true)
@TableId(value = "id", type = IdType.ID_WORKER)
private Long id;
@ApiModelProperty(value = "手机号", required = true)
private String phonenum;
@ApiModelProperty(value = "密码", required = true)
private String password;
@ApiModelProperty(value = "年龄", required = true)
private Integer age;
}