Swagger/Openapi-Annotations:如何使用 $ref 生成 allOf?

2022-01-22 00:00:00 swagger java openapi

我正在生成 Rest 端点，包括向生成的代码添加 Openapi/Swagger 注释.

I'm generating Rest endpoints including adding Openapi/Swagger annotations to the generated code.

虽然它适用于基本类型，但我对自定义类有一些问题.

While it works quite well with basic types, I have some problems with custom classes.

现在我有很多自定义类的重复架构条目(使用 @Schema(implementation = MyClass.class))，但至少需要的信息在那里.不过，我想找到一种方法来删除重复的架构条目，同时保留其他信息.

Right now I have a lot of duplicate schema entries for the custom classes (using @Schema(implementation = MyClass.class)) but at least the needed information is there. However I'd like to find a way to remove the duplicate schema entries while retaining the additional information.

在讨论 $ref 和缺少兄弟属性的 github 问题上，我发现 一个示例您将如何在 yaml 中手动编写它以获得我正在寻找的结果，但是我无法弄清楚如何设置注释以生成它.

On a github-issue discussing the $ref and lack of sibling properties I found an example how you would write it manually in yaml in order to get the result I'm looking for, however I can't figure out how to set the annotations to produce it.

如果我遵循 认为注释的样子" rel="noreferrer">example (只是为了安全起见，它被添加到 getter 和 setter 中):

This is how I think the annotation should look like if I follow the example (just to be on the safe side it is added to both the getter and the setter):

  import io.swagger.v3.oas.annotations.media.Schema;

  ...
public class SepaPaymentRequest {
  ...

  @Schema(name = "w307BetrBeg", description = "BETRAG BEGUENSTIGTER ", allOf = { com.diesoftware.services.utils.Betrag.class }, required = true)
  public void setW307BetrBeg(final Betrag w307BetrBeg) {
    this.w307BetrBeg = w307BetrBeg;
  }

  ...
}

但是当我获取 openapi.yaml (snippet) 时我得到了什么:

However what I get when I fetch the openapi.yaml (snippet):

    w307BetrBeg:
      $ref: '#/components/schemas/Betrag'

我想要什么:

    w307BetrBeg:
      title: 'Betrag'
      description: 'BETRAG BEGUENSTIGTER'
      allOf:
        - $ref: '#/components/schemas/Betrag'

任何提示都非常受欢迎.

Any hints are more than welcome.

推荐答案

我还没有找到使用注释的方法，即通过注释类.

I haven't found a way to do it using annotations, i.e. by annotating the class.

我认为可以这样做，通过:

I think it's possible to do, by:

  • 创建模型
  • 使用 ModelConverter 注入模型

当我说模型"时，我指的是 io.swagger.v3.oas.models.media.Schema 的一个实例.

When I say "a model" I mean an instance of io.swagger.v3.oas.models.media.Schema.

我认为你特别想创建和注入一个 io.swagger.v3.oas.models.media.ComposedSchema 实例，它支持 allOf.

In particular I think you'd want to create and inject a io.swagger.v3.oas.models.media.ComposedSchema instance, which supports allOf.

这样做(即创建模型实例)与手写 YAML 没有太大区别.

Doing this (i.e. creating model instances) isn't very different from hand-writing the YAML.

另一种可能性——我没有尝试过——可能是编写一个稍微不同的 ModelConverter，您将其安装到转换器链中.然后，拦截对 resolve 的调用，该调用返回一个 name 为 Betrag 的 SchemaObject，并且(有时?)将其替换为 ComposedSchema 使用 allOf 的实例.

Another possibility -- which I haven't tried -- might be to write a slightly different ModelConverter, which you install into the chain of converters. Then, intercept calls to resolve which return a SchemaObject whose name is Betrag, and (sometimes?) replace that with a ComposedSchema instance which uses allOf.

相关文章