Swagger Swagger 目录结构

Swagger 文件自动导入 Apifox 后出现目录重复的问题如何解决

Apifox

2023-12-11

假如你的 Apifox 项目中原本存在这样的目录结构。

随着后续接口的增多，你可能需要将某些目录组织在一起，然后在 Apifox 中新增了一个目录后，变成了这样的结构。

但是，后续通过定时的方式自动导入 Swagger 文件到这个项目的时候，你可能会惊讶为什么pet 和 store 这两个目录又新增了一遍，为什么不直接覆盖并更新到aa目录下呢？

出现这种情况是因为，你仅在 Apifox 中变动了目录结构，但是你本地项目的代码层面没有变动，所以它还会按照你本地的 Swagger 配置来生成目录。

也就是说，你需要在你的本地代码里用 Swagger 注解来配置相关的目录结构，以确保与在 Apifox 中变动的目录结构保持同步，这样才能避免问题。

我们来举一个简单的例子来说明一下怎么配置。

我们以 Swagger Petstore 开源项目为例，讲述 Swagger 文件自动导入 Apifox 后出现目录重复的问题该如何解决。

步骤 1：下载 Swagger 文件

打开 Swagger Petstore 开源项目，点击swagger.json文件，鼠标右键，将其存到电脑本地，如下图所示。

步骤 2：将 Swagger 文件导入 Apifox

打开 Apifox，创建一个项目后，选择“项目设置->导入数据->OpenAPI/Swagger->文件导入”，将上一个步骤已导出的 Swagger 格式的 JSON 文件导入即可。

导入之后你会看到生成了这样的目录结构。

步骤 3：更改目录结构

我们随便新建一个目录，姑且就先叫它aa吧，然后将pet和store这两个目录置于其下。

步骤 4：同步本地更改

当后续的 Swagger 文件导入更新的时候如果想要保持上一步的目录结构，需要在本地也做同步配置，比如在第一步的 Swagger 文件中，你需要做以下更改（在实际项目中配置 Swagger 注解）：

当然我们在实际的项目当中不可能一个个在 Swagger 文件里改的，我们一般都会在项目代码里配置相关的 Swagger 注解，由注解来帮我们生成对应的目录结构。

对应上述的 Swagger JSON，你可以使用 Springfox 库中的注解。以下是一个简单的 Java 类的示例，使用 Springfox 的注解来描述相似的 Swagger 文档：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;

@Api(tags = {"aa/pet", "aa/store", "user"})
public class PetStoreController {

    @ApiOperation(value = "Everything about your Pets")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "Success"),
            @ApiResponse(code = 400, message = "Bad Request"),
            @ApiResponse(code = 404, message = "Not Found")
    })
    public void petEndpoint() {
        // Implementation of the pet endpoint
    }

    //......其它操作
}

在上述代码中，@Api 注解用于定义标签，每个标签对应于 Swagger 中的一个 tag，@ApiOperation 用于描述每个具体的 API 操作，而 @ApiResponses 用于定义可能的响应。