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

问题描述

我正在生成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.

这是我思考的方式，如果我遵循示例(为了安全起见，将其同时添加到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(代码段)时会得到什么:

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'

任何提示都值得欢迎.

推荐答案

我还没有找到使用注释(即通过注释类)来做到这一点的方法.

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

我认为可以这样做，

• 创建模型
• 使用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.

尤其是我认为您想创建并注入一个支持allOf的io.swagger.v3.oas.models.media.ComposedSchema实例.

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，(有时?)将其替换为使用allOf的ComposedSchema实例.

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.

这篇关于Swagger/Openapi-Annotations:如何使用$ ref生成allOf?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持！