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.xiaoymingroupId>
            <artifactId>knife4j-spring-boot-starterartifactId>
        dependency>

2.2.2 配置 knife4j 相关配置

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

    /**
     * 通过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;
    }

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 {

    @Autowired
    private EmployeeService employeeService;
    @Autowired
    private 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