springdoc openapi

IMPORTANTE: springdoc-openapi v1.8.0 é a versão de código aberto mais recente com suporte para Spring Boot 2.xe 1.x.

Um suporte estendido para o projeto springdoc-openapi v1 está agora disponível para organizações que precisam de suporte além de 2023.

Para mais detalhes, sinta-se à vontade para entrar em contato: [email protected]

springdoc-openapi está no Open Collective. Se você ❤️ este projeto considere se tornar um patrocinador.

Este projeto é patrocinado por

Índice

• Documentação completa
• Introdução
• Começando
  • Biblioteca para integração springdoc-openapi com spring-boot e swagger-ui
  • Spring-boot com aplicativos OpenAPI Demo.
    • Código-fonte para aplicativos de demonstração.
    • Demonstração do Spring Boot 2 Web MVC com OpenAPI 3.
    • Demonstração Spring Boot 2 WebFlux com OpenAPI 3.
    • Demonstração Spring Boot 2 WebFlux com endpoints funcionais OpenAPI 3.
    • Demonstração Spring Boot 2 e Spring Hateoas com OpenAPI 3.
  • Integração da biblioteca em um projeto Spring Boot 3.x sem o swagger-ui:
  • Tratamento de erros para REST usando @ControllerAdvice
  • Adicionando informações de API e documentação de segurança
  • suporte spring-webflux com controladores anotados
• Agradecimentos
  • Colaboradores
  • Suporte Adicional

Documentação completa

Introdução

A biblioteca Java springdoc-openapi ajuda a automatizar a geração de documentação de API usando projetos Spring Boot. springdoc-openapi funciona examinando um aplicativo em tempo de execução para inferir a semântica da API com base nas configurações do Spring, estrutura de classes e várias anotações.

A biblioteca gera automaticamente documentação em páginas formatadas em JSON/YAML e HTML. A documentação gerada pode ser complementada usando anotações swagger-api .

Esta biblioteca suporta:

• OpenAPI3
• Spring-boot v3 (Java 17 e Jacarta EE 9)
• JSR-303, especificamente para @NotNull, @Min, @Max e @Size.
• Swagger-ui
• OAuth2
• Imagens nativas do GraalVM

O vídeo a seguir apresenta a Biblioteca:

• https://youtu.be/utRxyPfFlDw

Para suporte ao spring-boot v3 , certifique-se de usar springdoc-openapi v2

Este é um projeto baseado na comunidade, não mantido pelos Contribuidores do Spring Framework (Pivotal)

Começando

Biblioteca para integração springdoc-openapi com spring-boot e swagger-ui

• Implanta automaticamente o swagger-ui em um aplicativo Spring Boot 3.x
• A documentação estará disponível em formato HTML, usando os jars oficiais do swagger-ui.
• A página da UI do Swagger deverá estar disponível em http://server: port/context-path/swagger-ui.html e a descrição do OpenAPI estará disponível no seguinte URL para formato json: http://server:port/context -caminho/v3/api-docs
  • server : O nome do servidor ou IP
  • port : A porta do servidor
  • context-path : O caminho de contexto do aplicativo
• A documentação também pode estar disponível no formato yaml, no seguinte caminho: /v3/api-docs.yaml
• Adicione a biblioteca springdoc-openapi-ui à lista de dependências do seu projeto (nenhuma configuração adicional é necessária):

Maven

   < dependency >
      < groupId >org.springdoc</ groupId >
      < artifactId >springdoc-openapi-starter-webmvc-ui</ artifactId >
      < version >last-release-version</ version >
   </ dependency >

Gradle

implementation ' org.springdoc:springdoc-openapi-starter-webmvc-ui:latest '

• Esta etapa é opcional: para o caminho personalizado da documentação do swagger em formato HTML, adicione uma propriedade springdoc personalizada em seu arquivo de configuração do spring-boot:

 # swagger-ui custom path
springdoc.swagger-ui.path =/swagger-ui.html

Spring-boot com aplicativos OpenAPI Demo.

Código-fonte para aplicativos de demonstração.

Demonstração do Spring Boot 3 Web MVC com OpenAPI 3.

Demonstração Spring Boot 3 WebFlux com OpenAPI 3.

Demonstração Spring Boot 3 WebFlux com endpoints funcionais OpenAPI 3.

Demonstração do Spring Boot 3 e Spring Cloud Function Web MVC.

Demonstração Spring Boot 3 e Spring Cloud Function WebFlux.

Demonstração do Spring Boot 3 e Spring Cloud Gateway.

Integração da biblioteca em um projeto Spring Boot 3.x sem o swagger-ui:

• A documentação estará disponível na seguinte url para formato json: http://server: port/context-path/v3/api-docs
  • server : O nome do servidor ou IP
  • port : A porta do servidor
  • context-path : O caminho de contexto do aplicativo
• A documentação também estará disponível no formato yaml, no seguinte caminho: /v3/api-docs.yaml
• Adicione a biblioteca à lista de dependências do seu projeto. (Nenhuma configuração adicional é necessária)

Maven

   < dependency >
      < groupId >org.springdoc</ groupId >
      < artifactId >springdoc-openapi-starter-webmvc-api</ artifactId >
      < version >last-release-version</ version >
   </ dependency >

Gradle

implementation ' org.springdoc:springdoc-openapi-starter-webmvc-ui:latest '

• Esta etapa é opcional: para o caminho personalizado da documentação OpenAPI no formato Json, adicione uma propriedade springdoc personalizada em seu arquivo de configuração spring-boot:

 # /api-docs endpoint custom path
springdoc.api-docs.path =/api-docs

• Esta etapa é opcional: se você deseja desabilitar endpoints springdoc-openapi , adicione uma propriedade springdoc personalizada em seu arquivo de configuração spring-boot :

 # disable api-docs
springdoc.api-docs.enabled =false

Tratamento de erros para REST usando @ControllerAdvice

Para gerar a documentação automaticamente, certifique-se de que todos os métodos declarem as respostas do Código HTTP usando a anotação: @ResponseStatus.

Adicionando informações de API e documentação de segurança

A biblioteca usa pacotes configurados automaticamente do aplicativo spring-boot para procurar as seguintes anotações em spring beans: OpenAPIDefinition e Info. Essas anotações declaram informações da API: título, versão, licença, segurança, servidores, tags, segurança e documentos externos. Para melhor desempenho na geração de documentação, declare as anotações @OpenAPIDefinition e @SecurityScheme em um bean gerenciado Spring.

suporte spring-webflux com controladores anotados

• A documentação também pode estar disponível no formato yaml, no seguinte caminho: /v3/api-docs.yaml
• Adicione a biblioteca à lista de dependências do seu projeto (nenhuma configuração adicional é necessária)

Maven

   < dependency >
      < groupId >org.springdoc</ groupId >
      < artifactId >springdoc-openapi-starter-webflux-ui</ artifactId >
      < version >last-release-version</ version >
   </ dependency >

Gradle

implementation ' org.springdoc:springdoc-openapi-starter-webmvc-ui:latest '

• Esta etapa é opcional: para o caminho personalizado da documentação do swagger em formato HTML, adicione uma propriedade springdoc personalizada em seu arquivo de configuração do spring-boot:

 # swagger-ui custom path
springdoc.swagger-ui.path =/swagger-ui.html

As bibliotecas springdoc-openapi estão hospedadas no repositório central maven. Os artefatos podem ser visualizados e acessados ​​nos seguintes locais:

Lançamentos:

• https://s01.oss.sonatype.org/content/groups/public/org/springdoc/ .

Instantâneos:

• https://s01.oss.sonatype.org/content/repositories/snapshots/org/springdoc/ .

Agradecimentos

Colaboradores

springdoc-openapi é relevante e atualizado regularmente devido às valiosas contribuições de seus colaboradores.

Obrigado a todos pelo apoio!

Suporte Adicional

• Equipe Spring - Obrigado por seu apoio compartilhando todos os recursos relevantes em torno dos projetos Spring.
• JetBrains – Muito obrigado por apoiar o projeto springdoc-openapi.