合约第一代 OpenAPI

Question

我尝试使用一个简单的 OpenAPI V3 API 在 OpenLiberty 上实现契约优先范式。

我使用以下插件进行 OpenAPI 代码生成：

<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<version>3.2.2-SNAPSHOT</version>

对于生成我使用 <generatorName>jaxrs-spec</generatorName>

作为<configOptions>我使用<useSwaggerAnnotations>false</useSwaggerAnnotations>

在模型类旁边生成以下界面：

@Path("/inventory")
public interface InventoryApi {

  @GET
  @Path("/systems/{hostname}")
  @Produces({ "text/plain", "application/json" })
  Response getPropertiesForHost(@PathParam("hostname") String hostname);

  @GET
  @Path("/systems")
  @Produces({ "application/json" })
  Response listContents();
}

我尝试像这样尽可能精简地使用我的实现：

@RequestScoped
@Path("/")
public class InventoryImpl implements InventoryApi {

   public Response getPropertiesForHost(String hostname) {
      ...
   }

   public Response listContents() {
      ...
   }    
}

我可以使用以下 curl 命令调用 curl -X GET "http://localhost:9080/properties-sample/systems" 这有效！

但我希望使用以下内容 curl -X GET "http://localhost:9080/properties-sample/inventory/systems" 但这不起作用。我必须将 Impl 中的 @Path 更改为 @Path("/inventory")，因此它可以使用 curl -X GET "http://localhost:9080/properties-sample/inventory/systems"

这是按设计工作还是 @Path 界面上的注释无关紧要？

是否有人有另一种方法来使用 OpenLiberty 的契约优先范式？

Answer 1

您为此使用 OpenAPI 工具插件是正确的。 Open Liberty 支持 MicroProfile OpenAPI，它允许您公开您的合约优先 OAS3 文档，但出于生成目的，Open Liberty 遵从 OSS OpenAPI 工具社区。

This link 应该有助于指导您的界面与实施有关 JAX-RS 注释的 class 决策。特别是，在您的示例中，您覆盖了主 @Path 注释，因此行为不同。

合约第一代 OpenAPI

Contract First OpenAPI Generation

open-liberty

openapi-generator