java - Swagger - 如何使用 swagger-codegen 并长期构建项目

Question

Swagger 项目非常适合用各种语言轻松创建客户端和服务器应用程序，但我不明白如何以适当的方式维护或扩展现有项目。

我正在生成一个 Java 服务器 - 语言参数是 jaxrs-spec。

我已经编写了自己的 Maven pom 并使用了 swagger-codegen-maven-plugin，所以现在我可以直接使用 maven 生成模型或 api。

我发现每次重建我的项目时，API 都会被 swagger-codegen 插件完全重写。

我需要实现我的应用程序逻辑，目前除了自定义生成的 API 源之外我没有看到任何其他方法。 因此，为了避免在每次构建时丢失我的工作，我可以配置 .swagger-codegen-ignore(我确实这样做了)，但我只是推迟了这个问题。

因为第一次我必须更新 swagger.json，所以我唯一的选择是重新生成整个 API 并覆盖我的工作。好的，我可以使用 git 并尝试恢复删除的部分，但这确实是一个丑陋的解决方案。

所以，问题是:

使用 swagger-codegen(或一般的 Swagger)是否有一种模式、一种方法、一种记录的方式允许我添加行为和/或扩展生成的 API 而不会覆盖我的代码？

Answer 1

这取决于您选择的语言/模板，因为其中一些比其他的更灵活，但同样的原则也适用:您不应该在生成的代码中添加任何额外的逻辑。 不幸的是，通过查看 sample for jaxrs-spec ，这些模板看起来不如说的那些好，jaxrs-resteasy .

此时，您可以:

1. 将模板切换到不同的 jaxrs
2. 编写自己的模板并使用它们
3. 修改/更新 swagger-codegen 模板并将它们提交回来。

我将逐步解释如何为其他模板完成此操作。目前完成的方式是通过工厂，但它可以通过依赖注入(inject)轻松完成。 Codgen 生成作为 API 样板的 stub 实现，并将实际逻辑委托(delegate)给另一个类。

对于 jaxrs-resteasy，这是 codegen 为 GET/{username} 方法生成的内容(我删除了它也放入的 swagger 注释):

@GET
@Path("/{username}")
@Produces({ "application/xml", "application/json" })
public Response getUserByName( @PathParam("username") String username,@Context SecurityContext securityContext)
throws NotFoundException {
    return delegate.getUserByName(username,securityContext);
}

实际的方法只是委托(delegate)给一个工厂，它是这样获取的:

private final UserApiService delegate = UserApiServiceFactory.getUserApi();

它能做到这一点是因为它还为 API 生成了一个基类来实现:

public abstract class UserApiService {
    // methods omitted...
    public abstract Response getUserByName(String username, SecurityContext securityContext) throws NotFoundException;
    // methods omitted...
}

现在，在非生成代码中，用户添加了这个基类的实现:

public class UserApiServiceImpl extends UserApiService {
      // methods omitted...
      @Override
      public Response getUserByName(String username, SecurityContextsecurityContext) throws NotFoundException {
          // do some magic!
          return Response.ok().entity(new ApiResponseMessage(ApiResponseMessage.OK, "magic!")).build();
    }
    // methods omitted...
}

然后用户在codegen期望的package中添加factory，这样生成的代码就可以得到上面的实现:

public class UserApiServiceFactory {
   private final static UserApiService service = new UserApiServiceImpl();

   public static UserApiService getUserApi() {
      return service;
   }
}

现在生成的代码确切地知道要委托(delegate)给 UserApiService 的哪个实现。此时，整个服务器样板与应用程序逻辑分离，允许您重新生成 API 而无需覆盖您的自定义逻辑。

_{此答案假定 jaxrs-spec 的示例是 swagger-codegen 为该语言参数生成的内容的准确示例。有时它们会过时。}