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

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

此时，您可以：

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

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

对于jaxrs-resteasy ，这是jaxrs-resteasy为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);
}

实际的方法只是委托给一个工厂，它得到如下：

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期望的包中添加工厂，因此生成的代码可以获得上述实现：

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

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

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

_{这个答案假设jaxrs-spec的样本是swagger-codegen为该语言参数生成的一个准确示例。 有时他们会过时。}