黑马程序员最新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

1. 在 pom.xml中添加 Knife4j 依赖：

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

2. 在 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;
   }
   

3. 在 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/");
   }
   

4. 在浏览器中访问接口文档路径 http://localhost:8080/doc.html：

   

5. 接口测试，测试登录接口【login】：

   

常用注解

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

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

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

1. 修改 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();
       }
   
   }
   

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