合约优先 OpenAPI 生成

Posted 2023-04-15

【中文标题】合约优先 OpenAPI 生成

【英文标题】：Contract First OpenAPI Generation

【发布时间】：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 中使用契约第一范式的方法？

【参考方案1】：

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

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