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為該語言參數生成的一個准確示例。 有時他們會過時。}