Swagger（测试接口）

Swagger介绍

使用Swagger你只需要按照它的规范去定义接口及接口相关的信息，就可以做到生成接口文档，以及在线接口调试页面。官网: https://swaggeriol

Knife4j介绍

Knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案。

Knife4j 是一款基于 Swagger 的文档生成工具，它的目标是让开发者更简单、更方便地生成 API 文档。与原生的 Swagger 相比，Knife4j 提供了更加丰富的功能和更好的用户体验。以下是 Knife4j 的一些主要特性：

1. **UI界面优化**：Knife4j 提供了一个更加现代和美观的用户界面，改善了原生 Swagger UI 的用户体验。
2. **多语言支持**：除了支持中文，Knife4j 还支持其他多种语言，方便不同国家和地区的开发者使用。
3. **API 调试**：在 UI 中直接对 API 进行调试，无需切换到其他工具，提高开发效率。
4. **文档导出**：支持将 API 文档导出为 Markdown、HTML 等多种格式，方便分享和发布。
5. **自定义扩展**：可以通过配置文件或编程方式对 Swagger 的配置进行自定义，满足特定需求。
6. **注解支持**：继承了 Swagger 的注解体系，可以很容易地与现有的代码集成。
7. **全局参数/响应**：支持全局参数配置和全局响应结构，简化了公共逻辑的管理。
8. **认证支持**：支持多种认证方式，如 BasicAuth、OAuth2 等，方便 API 的安全访问。
9. **分组管理**：可以将相关的 API 进行分组管理，使得文档更加清晰有序。
10. **模板引擎**：支持使用 Freemarker 模板引擎自定义文档的渲染方式。

Knife4j的坐标

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

knife4j的配置方式

knife4j作为一个管理接口和测试接口的工具，其主要作用在前后端联调，因此虽然可以写成独立的配置类，但最好在WebMvcConfiguration进行配置方便管理。

下面是在WebMvcConfiguration进行配置的一个例子：

/**
     * 通过knife4j生成接口文档
     * @return
     */
    @Bean
    public Docket docket() {
        ApiInfo apiInfo = new ApiInfoBuilder()
                //接口文档标题
                .title("苍穹外卖项目接口文档")
                //版本
                .version("2.0")
                //简介
                .description("苍穹外卖项目接口文档")
                .build();
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                //管理接口扫描的包
                .apis(RequestHandlerSelectors.basePackage("com.sky.controller"))
                //指定所有的api路径
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

配置knife4j生成的接口文档的静态资源映射

knife4j为我们生成了接口文档，我们也一定不能忘记设置静态资源映射。

    /**
     * 设置静态资源映射
     * @param registry
     */
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

 配置拦截器放行

示例： 

/**
     * 注册拦截器
     * @param registry
     */
    protected void addInterceptors(InterceptorRegistry registry ){
        // 对swagger的请求不进行拦截
        String[] excludePatterns = new String[]{"/swagger-resources/**", "/webjars/**", "/v2/**", "/swagger-ui.html/**",
                "/api", "/api-docs", "/api-docs/**", "/doc.html/**"};
        registry.addInterceptor(jwtTokenInterceptor).addPathPatterns("/**")
                .excludePathPatterns("/user/login")
                .excludePathPatterns("/user/register")
                .excludePathPatterns(excludePatterns);
    }

Swagger的常用注解

配置这些注解可以让你的接口文档更加完善 

@Api

用在类上，例如Controller,表示对类的说明

/**
 * 员工管理
 */
@RestController
@RequestMapping("/admin/employee")
@Slf4j
@Api( tags = "员工相关接口")
public class EmployeeController {
}

@ApiModel

用在类上，例如entity、DTO、VO

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(description = "员工登录返回的数据格式")
public class EmployeeLoginVO implements Serializable {

    @ApiModelProperty("主键值")
    private Long id;

    @ApiModelProperty("用户名")
    private String userName;

    @ApiModelProperty("姓名")
    private String name;

    @ApiModelProperty("jwt令牌")
    private String token;

}

@ApiModelProperty

用在属性上，描述属性信息

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(description = "员工登录返回的数据格式")
public class EmployeeLoginVO implements Serializable {

    @ApiModelProperty("主键值")
    private Long id;

    @ApiModelProperty("用户名")
    private String userName;

    @ApiModelProperty("姓名")
    private String name;

    @ApiModelProperty("jwt令牌")
    private String token;

}

@ApiOperation

用在方法上，例如如Controller的方法，说明方法的用途、作用
 

 /**
     * 登录
     *
     * @param employeeLoginDTO
     * @return
     */
    @ApiOperation("员工登录")
    @PostMapping("/login")
    public Result<EmployeeLoginVO> login(@RequestBody EmployeeLoginDTO employeeLoginDTO) {
        log.info("员工登录：{}", employeeLoginDTO);

        Employee employee = employeeService.login(employeeLoginDTO);

        //登录成功后，生成jwt令牌
        Map<String, Object> claims = new HashMap<>();
        claims.put(JwtClaimsConstant.EMP_ID, employee.getId());
        String token = JwtUtil.createJWT(
                jwtProperties.getAdminSecretKey(),
                jwtProperties.getAdminTtl(),
                claims);

        EmployeeLoginVO employeeLoginVO = EmployeeLoginVO.builder()
                .id(employee.getId())
                .userName(employee.getUsername())
                .name(employee.getName())
                .token(token)
                .build();

        return Result.success(employeeLoginVO);
    }