knife4j集成Swagger

news2024/10/5 16:28:10

knife4j集成

`配置knife4j`

第一步: 导入knife4j对应的maven坐标,knife4j是为MVC框架集成Swagger生成API文档的增强解决方案

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

第二步: 在WebMvcConfig配置类中设置knife4j的相关配置, 使用@EnableSwagger2WebMvc注解开启生成接口文档的功能

@Configuration
@Slf4j
@EnableSwagger2 // 集成Swagger的注解
@EnableKnife4j
//@EnableSwagger2WebMvc // 该注解可以代替以上两个注解
public class WebMvcConfig extends WebMvcConfigurationSupport {
    // 描述接口信息的文档对象
    @Bean
    public Docket createRestApi() {
        //文档类型
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
            	// 扫描controller中的控制器方法生成对应的接口文档 
                .apis(RequestHandlerSelectors.basePackage("com.reggie.controller"))
                .paths(PathSelectors.any())
                .build();
    }
	
    // 描述文档信息的对象	
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("瑞吉外卖")
                .version("1.0")
                .description("瑞吉外卖接口文档")
                .build();
    }
}

第三步: 设置静态资源映射, 否则接口文档页面无法访问

public class WebMvcConfig extends WebMvcConfigurationSupport {
    @Override
    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/");
    }
}

第四步: 在LoginCheckFilter拦截器对访问接口文档的请求路径放行即用户没有登陆时也允许访问

// 定义不需要处理的请求
String[] urls = new String[]{
        "/employee/login",
        "/employee/logout",
        "/backend/**",
        "/front/**",
        "/common/**",
        // 对用户登陆操作放行
        "/user/login",
        "/user/sendMsg",
		// 对文档的访问操作放行
        "/doc.html",
        "/webjars/**",
        "/swagger-resources",
        "/v2/api-docs"
};

第五步: 启动服务访问http://localhost:8080/doc.html即可看到生成的接口文档

在这里插入图片描述

第六步: 导出离线文档,OpenAPI表示导出JSON格式的文档,可以在Yapi平台中使用

在这里插入图片描述

`常用注解`

使用knife4j提供的这些注解可以将我们生成的接口文档更规范

注解	说明
@Api	一般用在请求的Controller类上,表示对类的说明
@ApiOperation	用在Controller类中请求的方法上，说明方法的用途
@ApilmplicitParams	用在Controller类中请求的方法上，对控制器方法中的参数进行说明
@ApilmplicitParam	用在@ApilmplicitParams注解中，指定一个请求参数的各个方面
@ApiModel	一般用在是个实体类上，表示一个返回响应数据的信息
@ApiModelProperty	用在实体类的属性上，描述响应类的属性

在实体类上使用@ApiModel和@ApiModelProperty

@Data
@ApiModel("用户")
public class User implements Serializable {
    private static final long serialVersionUID = 1L;
    @ApiModelProperty("主键")
    private Long id;
    //姓名
    @ApiModelProperty("姓名")
    private String name;
    //手机号
    @ApiModelProperty("手机号")
    private String phone;
    //性别 0 女 1 男
    @ApiModelProperty("性别 0 女 1 男")
    private String sex;
    //身份证号
    @ApiModelProperty("身份证号")
    private String idNumber;
    //头像
    @ApiModelProperty("头像")
    private String avatar;
    //状态 0:禁用，1:正常
    @ApiModelProperty("状态 0:禁用，1:正常")
    private Integer status;
}

在控制器方法上使用@Api和@ApiOperation以及@ApilmplicitParams注解

@RestController
@Slf4j
@RequestMapping("/user")
@Api(tags = "用户相关接口")
public class UserController {
    @PostMapping("/sendMsg")
    @ApiOperation("发送验证邮件接口")
    public Result<String> sendMsg(@RequestBody User user) throws MessagingException {
    }
    @PostMapping("/login")
    @ApiOperation("用户登录接口")
    @ApiImplicitParam(name = "map",value = "map集合接收数据",required = true)
    public Result<User> login(@RequestBody Map map, HttpSession session) {
     
    }
    @PostMapping("/loginout")
    @ApiOperation("用户登出接口")
    public Result<String> logout(HttpServletRequest request) {
    }
}