Add support for OpenAPI spec 3.2

Aberta
  • Algo errado?
#3,324 2 comentários 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
4/5
Tempo estimado
3-5 dias
Facilidade para iniciantes
48/100
Tipo de issue
Funcionalidade
Clareza
Razoavelmente clara
Status de atividade
Pouca atividade
Stack de tecnologia
java, openapi, spring-boot
Domínio
api, backend

Direção de pesquisa

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.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

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.

Linguagem predominante
Java
Estrelas
3.7k
Forks
605
Merge médio
3d 15h
PRs com merge (30d)
19

Preparar o ambiente

Este projeto não oferece contêiner de desenvolvimento, Dockerfile nem guia de contribuição, então a configuração fica por sua conta: comece pelo README e veja nosso guia da primeira contribuição para os passos gerais.

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de springdoc/springdoc-openapi

Todas as issues de springdoc/springdoc-openapi

Issues semelhantes

Mais issues de Java

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.