合约优先 OpenAPI 生成答案

【问题标题】：Contract First OpenAPI Generation合约优先 OpenAPI 生成
【发布时间】：2019-01-27 19:48:52
【问题描述】：

我尝试使用简单的 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 中使用契约第一范式的方法？

【问题讨论】：

标签： open-liberty openapi-generator

【解决方案1】：

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

This link 应该有助于指导您的接口与实现有关 JAX-RS 注释的类决策。特别是，在您的示例中，您将覆盖主要的 @Path 注释，因此行为不同。

【讨论】：