一、前后端分离开发流程

1.1 操作步骤

1. 将接口文档导入API测试工具（如：Apifox/Postman）
2. 前后端根据接口文档并行开发
3. 使用Swagger维护实时接口文档
4. 进行前后端联调测试

二、Swagger集成方案

2.1 Swagger介绍和使用方式

• Swagger：行业标准API文档工具,使用swagger你只需要按照它的规范去定义接口及接口相关的信息,就可以做到生成接口文档,以及在线接口调试页面,官网 : https://swagger.io/
• Knife4j：是为Java MVC框架集成Swagger生成Api文档的增强解决方案，提供更友好的UI界面

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

2.2 使用方式

1. 添加 knife4j 的Maven依赖

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

2. 在配置类中加入 knife4j 相关配置,设置静态资源映射，否则接口文档页面无法访问

/**
 * 配置类，注册web层相关组件
 */
@Configuration
@Slf4j
public class WebMvcConfiguration extends WebMvcConfigurationSupport {


    /**
     * 通过knife4j生成接口文档
     * @return
     */
    @Bean
    public Docket docket() {
        log.info("准备生成接口文档...");
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("苍穹外卖项目接口文档")
                .version("2.0")
                .description("苍穹外卖项目接口文档")
                .build();

        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                // 指定生成接口需要扫描的包,也就是项目中的controller路径
                .apis(RequestHandlerSelectors.basePackage("com.sky.controller")) 
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

    /**
     * 设置静态资源映射
     * @param registry
     */
    //addResourceHandlers这个方法名不能随便写,这个方法是重写的父类中的方法
    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/");
    }
}

3. 访问文档

 http://localhost:8080/doc.html

思考:

三、Swagger常用注解

3.1 常用注解列表

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

注解	应用位置	作用描述
@Api	用在类上,例如Controller类,表示对类的说明	模块分类标签
@ApiOperation	用在方法上，例如Controller 的方法，说明方法的用途、作用	接口功能描述
@ApiModel	用在类上,例如entity、DTO、 VO	数据模型说明
@ApiModelProperty	用在属性上,描述属性信息	字段属性说明
@ApiParam	方法参数	单个参数说明

3.2 示例

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();
    }

}

DTO对象配置

@Data
@ApiModel(description = "员工登录时传递的数据模型")
public class EmployeeLoginDTO implements Serializable {

    @ApiModelProperty("用户名")
    private String username;

    @ApiModelProperty("密码")
    private String password;

}

加入后,就有了自己定义的注解

四、安全配置建议

4.1 生产环境配置

Properties# application-prod.properties
knife4j.enable=false
swagger.enabled=false

4.2 访问白名单配置

Java@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
            .antMatchers("/doc.html").permitAll()
            .antMatchers("/webjars/**").permitAll()
            .antMatchers("/v2/api-docs").permitAll();
    }
}

五、排错指南

5.1 常见问题排查

现象	可能原因	解决方案
404访问不到文档页面	静态资源未正确映射	检查addResourceHandlers配置
接口未显示	包扫描路径错误	确认basePackage指向正确Controller包
文档字段显示不正确	DTO注解缺失	添加@ApiModelProperty注解
接口参数说明缺失	方法参数未加@ApiParam	补充参数说明注解

5.2 调试技巧

1. 访问/v2/api-docs查看原始JSON数据
2. 清理浏览器缓存后重试
3. 检查控制台启动日志中的Swagger初始化信息

通过规范使用Swagger和Knife4j，可以显著提升团队协作效率，保证API文档的实时性和准确性。建议结合CI/CD流程实现文档的自动化更新与部署。