Add support for OpenAPI spec 3.2

Offen
  • Stimmt etwas nicht?
#3,324 2 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Maintainer antworten meist innerhalb von 1 Tag

Dieses Issue hat noch niemand übernommen.

Bewertung

Schwierigkeit
4/5
Geschätzter Aufwand
3-5 Tage
Anfängerfreundlichkeit
48/100
Issue-Typ
Feature
Klarheit
Größtenteils klar
Aktivitätsstatus
Ruhig
Tech-Stack
java, openapi, spring-boot
Bereich
api, backend

Rechercherichtung

Start by reading how springdoc generates api-docs and handles OpenAPI specification versions, then compare its current 3.1 support with the requested 3.2 behavior. Done means springdoc can generate api-docs using version 3.2.x and represent the XML element with attributes and text content as described.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

enhancement upstream

Is your feature request related to a problem? Please describe.

My problem is that I want to describe an XML schema and generate examples that have an element with attributes and a text-type child element:

<request>
  <signature version="2.0">123abc</signature>
</request>

The result when translating the DAO with JAXB

@Schema
@XmlRootElement(name = "request")
public class Request {
  @XmlElement(name = "signature")
  public Signature signature;

  public class Signature {
    @Schema(example = "2.0")
    @XmlElement(name = "version")
    public String version;

    @Schema(example = "123abc")
    @XmlValue
    public String value;
}

but rendering it with springdoc 2.8.17 and OpenAPI 3.1 gives me the api-docs:

<request>
  <signature version="2.0">
    <value>123abc</value>
  </signature>
</request>

Describe the solution you'd like
The lack of support for this stems from OpenAPI not supporting this as of spec 3.1. There was an issue filed for OpenAPI-Specification https://github.com/OAI/OpenAPI-Specification/issues/630. It was implemented in https://github.com/OAI/OpenAPI-Specification/pull/4592 and released in https://github.com/OAI/OpenAPI-Specification/releases/tag/3.2.0.

So I'd like springdoc to add support for api-docs version 3.2.x.

Describe alternatives you've considered
My alternative for now is to hard-code the example into my api-docs and accept the wrong looking schema until newer OpenAPI spec versions.

Vorherrschende Sprache
Java
Sterne
3.7k
Forks
605
Ø Merge
4 T. 18 Std.
Gemergte PRs (30 T.)
21

Entwicklungsumgebung

Dieses Projekt bietet weder Dev-Container noch Dockerfile noch Beitragsleitfaden – die Einrichtung liegt bei Ihnen. Beginnen Sie mit der README; die allgemeinen Schritte stehen in unserem Leitfaden für den ersten Beitrag.

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus springdoc/springdoc-openapi

Alle Issues in springdoc/springdoc-openapi

Ähnliche Issues

Weitere Issues zu Java

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.