前言

终于开始学习做项目了，本篇文章是学习B站黑马程序员苍穹外卖的学习笔记。我的学习路线是Java基础语法-JavaWeb-做项目，登录功能结束后，就进入复杂功能的开发，在进行前后端测试通常使用API 开发工具Swagger 自动生成接口。

🙌什么是Swagger？

其实讲的时候我也很懵，讲的课件的原话是：“你只需要按照规范定义接口，生成接口文档，以及在线接口调试页面就行”，我让ai解释了一下：Swagger 是一个流行的 API 开发工具，它帮助开发者设计、构建、记录以及使用 RESTful 风格的 Web 服务。（反正我也没太看懂😵‍💫）

我根据我学web的时候用的Apifox（这个真的很好用）来看他俩应该差不多，但Swagger能根据我们写的代码自动生成测试。

🛠️ Swagger 的三大功能：

1. 自动生成 API 文档
   你写了一个接口，Swagger 自动把它变成网页版的文档。
   网页上清晰地列出所有接口：路径、方法、参数、返回值等。

2. 支持在线测试接口
   不用手动写 Postman 请求，直接在 Swagger 页面上点击按钮就能调用接口。

3. 接口规范统一
   所有接口都有统一格式，方便前后端沟通协作。

🔍再来看看使用：

1. 导入knife4j的maven坐标

<!-- Knife4j UI 替代默认的 Swagger UI 页面 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.5.0</version> <!-- 注意版本匹配 Spring Boot 版本 -->
</dependency>

这个就直接导入复制粘贴就行

2. 在配置类中假如 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. 设置静态资源映射，否则接口文档页面无法访问

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

这个我感觉就没有必要理解太深，里面还有什么反射啥的，什么通过反射获取controller包下所有的接口信息,包括请求方式路径形参,根据这些信息创建相应的假数据，把controller 反射到文档 返到前端😵‍💫😵‍💫😵‍💫，只要会用吧

🙌还有一些常见注释，主要是使生成的前端界面更丰富好用

这是课件上的解释，下面是用法：
@Api：用于描述整个控制器的功能
@ApiOperation：用于描述一个具体的 API 操作

来看代码(主要在controller层运用)：

...

/**
 * 员工管理
 */
@RestController
@RequestMapping("/admin/employee")
@Slf4j
@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) {
        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);
    }

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

    /**
     * 新增员工
     * @param employeeDTO
     * @return
     */
    @PostMapping
    @ApiOperation("新增员工")
    public Result save(@RequestBody EmployeeDTO employeeDTO) {
        log.info("新增员工，员工数据：{}", employeeDTO);
        employeeService.save(employeeDTO);
        return Result.success();
    }

    /**
     *分页查询
     * @param employeePageQueryDTO
     */
    @GetMapping("/page")
    @ApiOperation("员工分页查询")
    public Result<PageResult> page(EmployeePageQueryDTO employeePageQueryDTO) {
        log.info("员工分页查询,参数为{}",employeePageQueryDTO);
        PageResult pageResult = employeeService.pageQuery(employeePageQueryDTO);
        return Result.success(pageResult);
    }

    /**
     * 修改员工状态
     * @param status
     * @param id
     * @return
     */

    @PostMapping("/status/{status}")
    @ApiOperation("员工状态禁用/启用")
    public Result startOrStop(@PathVariable Integer status, Long id) {
        log.info("员工状态禁用/启用：{},{}", status,id);
        employeeService.startOrStop(status, id);
        return Result.success();
    }



}