【无标题】

最新推荐文章于 2024-08-29 17:06:37 发布

Sunny__Guo

最新推荐文章于 2024-08-29 17:06:37 发布

阅读量81

点赞数

文章标签： spring boot spring java

本文链接：https://blog.csdn.net/Sunny__Guo/article/details/127689464

版权

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;
}