最适合新手的SpringBoot+SSM项目《苍穹外卖》实战—（四）集成 Swagger

文章目录

黑马程序员最新Java项目实战《苍穹外卖》，最适合新手的SpringBoot+SSM的企业级Java项目实战。

Swagger 介绍

Swagger 是一个开源的 API 设计工具，它可以用于描述、设计、开发和测试 RESTful API。它提供了一种标准化的方式来描述和呈现 RESTful API，可以根据 API 文档生成客户端和服务器代码，从而加快 API 的开发和部署工作。通过 Swagger，开发人员可以使用简单而强大的 API 交互来快速构建、测试和部署 RESTful 应用程序。

Spring 已经将Swagger纳入自身的标准，建立了Spring-swagger项目，现在叫 Springfox。通过在项目中引入 Springfox ，即可非常简单快捷的使用Swagger。

与 YApi 不同的是，Yapi 是设计阶段使用的工具，管理和维护接口；Swagger 是在开发阶段使用的框架，帮助后端开发人员做后端的接口测试。

而 Knife4j 是一个 Swagger 前端 UI 增强库，它基于 Swagger 生成 API 文档，并提供了更加强大的 UI 界面和交互体验。Knife4j 提供了丰富的特性，如接口测试、接口在线调试、接口文档导出等，大大提高了 API 开发的效率和可靠性。Knife4j 是基于 SpringBoot 和 SpringMvc 开发的，支持多种文档格式的导出，也支持自定义UI风格和主题。Knife4j 是开源的，可自由使用和修改。

集成 Swagger

在 pom.xml中添加 Knife4j 依赖：

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

在 WebMvcConfiguration.java 配置类中加入 Knife4j 相关配置：

/**
* 通过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"))
    .paths(PathSelectors.any())
    .build();
  return docket;
}

在 WebMvcConfiguration.java 中设置静态资源映射，否则接口文档页面无法访问：

/**
* 设置静态资源映射
* @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/");
}

在浏览器中访问接口文档路径 http://localhost:8080/doc.html：
接口测试，测试登录接口【login】：

常用注解

通过 Swagger 提供的注解可以控制生成的接口文档，使接口文档拥有更好的可读性，常用注解如下：

注解	说明
@Api	用在类上，例如Controller，表示对类的说明
@ApiModel	用在类上，例如entity、DTO、VO
@ApiModelProperty	用在属性上，描述属性信息
@ApiOperation	用在方法上，例如Controller的方法，说明方法的用途、作用

接下来，使用上述注解，生成可读性更好的接口文档。

修改 sky-server模块中 EmployeeController.java 类，分别在类上方法上添加 @Api、@ApiOperation 注解：

@Api(tags = "员工相关接口")
public class EmployeeController {
      
      

    @PostMapping("/login")
    @ApiOperation(value = "员工登录")
    public Result<EmployeeLoginVO> login(@RequestBody EmployeeLoginDTO employeeLoginDTO) 	{
      
      
        //..............
    }

    @PostMapping("/logout")
    @ApiOperation("员工退出")
    public Result<String> logout() {
      
      
        return Result.success();
    }

}

启动服务：访问 http://localhost:8080/doc.html