如何使用Openapi Generator从Swagger yaml生成SpringBoot模型

Question

我们采用 API 优先的方法，我们服务的 API 在 Swagger yamls 中定义。然后我们使用 Openapi generator 生成必须由微服务实现的接口。此外，模型是从架构中生成的。

这就是问题所在。在 REST 端点中的一个地方，我消耗 XML 并让 Spring-boot 将其解析为模型，然后将其保存到数据库中。目前，我使用类似于以下内容的模型：

@Data
@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
@Document("MyModel")
public class Model {

  @Id 
  @XmlTransient
  private String id;

  @XmlAttribute
  private String someAttribute;

  @XmlElement("childName")
  private List<OtherModel> children;

  @XmlElement("otherChildName")
  private List<OtherModel2> children2; 

}

其他模型非常相似。我喜欢这个，因为Spring-boot可以使用它自动解析传入的XML，并且我可以直接将此模型保存到数据库并作为JSON返回。

由Openapi Generator生成的模型缺少注释，因此无法用于解析XML并且无法保存到数据库。在yaml中有没有任何方法告诉它添加@Id，@Document和一些@Xml...注释？

我尝试使用自动生成的swagger模型的主要原因是，这是一个较大的架构，如果有人更改了yaml中的API定义，并且例如添加了字段，则微服务也将重新构建，并且模型将更新而无需手动更新Java类。我考虑的另一种方法是像Openapi那样生成模型，然后使用自己的类进行扩展，然后再添加注释，但我想不出任何方法来做到这一点，以便在定义更改时不必更改派生类。

示例：

//class generated by openapigenerator
public class Model {
  private String field;
  private List<Submodel> children

  //autogenerated getters/setters
}

//model in my code
@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
@Document("MyModel")
public class MyModel extends Model {

  @Id 
  @XmlTransient
  @Getter
  @Setter
  private String id;

}

这样做也可以，但一些字段缺少@Xml...注释。我发现它能够很好地生成@JsonProperty("somename")，以适应json命名，但似乎在yaml中使用XML:name/attribute属性对生成的java代码没有任何影响（或者我做错了什么，尝试了这个：Documentation）。

我能想到的唯一方法就是重写getter/setters并用属性进行注释，但这意味着我必须触及使用API定义的模型派生的每个微服务。我无法将派生类移动到API项目中，因为上下文（在本例中为XML/mongo）可能会因微服务而异。

有关此问题的良好方法有什么建议吗？

干杯

在深入研究后，我越来越确信正确的方法可能是按照文档中提到的方式在swagger yaml中添加XML映射(@XmlAttribute/@XmlElement)注释，然后在微服务代码中进行扩展以添加数据库注释。基本上像第二个例子一样，只是在基类中，XML注释将已经由swagger codegen生成。然而，我尚未成功使swagger codegen在构建模式/模型时生成任何XML注释。

- Tom

Answer 1

首先，要让openapi生成XML注释，您需要在配置中将withXml标志设置为true。

我采用了在openapi yaml文件中使用XML规范来生成带有XML注释的模型的方法，该模型由Spring Boot用于解析传入的XML文件。

然后，像第二个示例一样，我衍生出另一个类并添加了id和数据库注释。

我认为这是一个好的方法，原因如下：

1. 如果更改openapi yaml（例如添加新字段到XML或类似内容），则微服务的代码无需更改即可反映新字段，只需重新构建/重新部署。

2. 它反映了层之间的差异，生成的模型反映了Http层上发生的情况，而派生的模型反映了数据库层所需的情况。

- Tom