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

Question

Swagger项目非常适合在每种语言中轻松创建客户端和服务器应用程序,但我不了解如何以适当的方式维护或扩展现有项目.

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

我已经编写了自己的Mavenpom并使用了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,这是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);
}

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

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为该语言参数产生的准确示例.有时他们会过时.}