Swagger/Openapi-Annotations: How to produce allOf with $ref?

问题

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.

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.

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.

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;
  }

  ...
}

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

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

What I'd like to have:

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

Any hints are more than welcome.

回答1:

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:

Creating a model
Injecting the model using a ModelConverter

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

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

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

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.

来源：https://stackoverflow.com/questions/57459520/swagger-openapi-annotations-how-to-produce-allof-with-ref

标签

java

swagger

openapi