Swagger

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）是否有模式、操作方法、记录的方式允许我添加行为 and/or 扩展生成的 APIs不覆盖我的代码？

Answer 1

这取决于您选择的语言/模板，因为其中一些比其他的更灵活，但同样的原则也适用：您不应该在生成的文件中添加任何额外的逻辑code. 不幸的是，通过查看 sample for jaxrs-spec, these templates don't look as good as the ones for say, jaxrs-resteasy.

此时，您可以：

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

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

对于 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 生成一个基础 class 来实现：

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

现在，在 non-generated 代码中，用户添加了此基础的实现 class:

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

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

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

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

Swagger - how to use swagger-codegen and build a project on the long term

java

maven

swagger-2.0

swagger-codegen