Java项目实战《苍穹外卖》 四、Swagger接口文档

以铜为镜，可以正衣冠；以人为镜，可以明得失；以史为镜，可以知兴替。 - - - 李世民

系列文章目录

苍穹外卖是黑马程序员2023年的Java实战项目，作为业余练手用，需要源码或者课程的可以找我，无偿分享

1. Java项目实战《苍穹外卖》 一、项目概述
2. Java项目实战《苍穹外卖》 二、项目搭建
3. Java项目实战《苍穹外卖》 三、登录功能
4. Java项目实战《苍穹外卖》 四、Swagger接口文档

---

---

一、YApi

1.1 官网

YApi官网地址： https://yapi.pro/#

1.2 添加项目

1.3 导入接口文档

资源网盘地址： https://pan.baidu.com/s/1i_7Xxw22lX6VtlmgWoQP-A?pwd=yv9g

1.4 接口文档

---

二、Swgger

2.1 介绍

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化的 Web 服务。

Knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望它能像一把匕首一样小巧,轻量,并且功能强悍!

2.2 使用步骤

2.2.1 导入 knife4j 的maven坐标

编辑 sky-server/pom.xml 文件：

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

2.2.2 配置 knife4j 相关配置

编辑 sky-server/src/main/java/com/sky/config/WebMvcConfiguration.java 文件：

    /*** 通过knife4j生成接口文档* @return*/@Beanpublic 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;}

2.2.3 设置静态资源映射

编辑 sky-server/src/main/java/com/sky/config/WebMvcConfiguration.java 文件：

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

2.2.4 访问文档

接口文档地址： http://localhost:8080/doc.html

2.3 注解

2.3.1 常用注解

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

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

2.3.2 DTO

编辑 sky-pojo/src/main/java/com/sky/dto/EmployeeLoginDTO.java 文件：

@Data
@ApiModel(description = "员工登录时传递的数据模型")
public class EmployeeLoginDTO implements Serializable {@ApiModelProperty("用户名")private String username;@ApiModelProperty("密码")private String password;}

2.3.3 VO

编辑 sky-pojo/src/main/java/com/sky/vo/EmployeeLoginVO.java 文件：

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

2.3.4 Controller

编辑 sky-server/src/main/java/com/sky/controller/admin/EmployeeController.java 文件：

/*** 员工管理*/
@RestController
@RequestMapping("/admin/employee")
@Slf4j //这是lombok的输出日志注解，这个日志信息更加完整，包含类的完整名，日志打印的时间
@Api(tags = "员工相关接口")
public class EmployeeController {@Autowiredprivate EmployeeService employeeService;@Autowiredprivate JwtProperties jwtProperties;/*** 登录* @param employeeLoginDTO* @return*/@PostMapping("/login")@ApiOperation(value = "员工登录")public Result<EmployeeLoginVO> login(@RequestBody EmployeeLoginDTO employeeLoginDTO, HttpSession session) {log.info("员工登录：{}", employeeLoginDTO);Employee employee = employeeService.login(employeeLoginDTO);//将登录数据员工id存储到session会话中session.setAttribute("employee",employee.getId());//生成令牌Map<String, Object> claims = new HashMap<>();//将员工的id写入载荷claims.put(JwtClaimsConstant.EMP_ID,employee.getId());String token = JwtUtil.createJWT(jwtProperties.getAdminSecretKey(),jwtProperties.getAdminTtl(),claims);//由于EmployeeLoginVO 使用@Builder注解就可以使用链式构建对象EmployeeLoginVO employeeLoginVO = EmployeeLoginVO.builder().id(employee.getId()).userName(employee.getUsername()).name(employee.getName()).token(token).build();return Result.success(employeeLoginVO);}/*** 退出* @return*/@PostMapping("/logout")@ApiOperation(value = "员工退出")public Result<String> logout() {return Result.success();}}

2.3.5 访问文档

接口文档地址： http://localhost:8080/doc.html