Add support for OpenAPI spec 3.2

Ouverte
  • Quelque chose ne va pas ?
#3,324 2 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

Personne n'a encore pris cette issue.

Évaluation

Difficulté
4/5
Temps estimé
3-5 jours
Accessibilité débutants
48/100
Type d'issue
Fonctionnalité
Clarté
Plutôt claire
Activité
Calme
Stack technique
java, openapi, spring-boot
Domaine
api, backend

Piste de recherche

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.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

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.

Langage dominant
Java
Étoiles
3.7k
Forks
605
Merge moyen
4 j 18 h
PR mergées (30 j)
21

Préparer son environnement

Ce projet ne fournit ni conteneur de développement, ni Dockerfile, ni guide de contribution : l'installation est à votre charge. Commencez par son README, et consultez notre guide de la première contribution pour les étapes générales.

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de springdoc/springdoc-openapi

Toutes les issues de springdoc/springdoc-openapi

Issues similaires

Plus d'issues Java

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.