springdoc openapi

IMPORTANTE: springdoc-openapi v1.8.0 es la última versión de código abierto que admite Spring Boot 2.x y 1.x.

Ya está disponible un soporte ampliado para el proyecto springdoc-openapi v1 para organizaciones que necesiten soporte más allá de 2023.

Para obtener más detalles, no dude en comunicarse con: [email protected]

springdoc-openapi está en Open Collective. Si ❤️ este proyecto considera convertirte en patrocinador.

Este proyecto está patrocinado por

Tabla de contenido

• Documentación completa
• Introducción
• Empezando
  • Biblioteca para la integración de springdoc-openapi con spring-boot y swagger-ui
  • Spring-boot con aplicaciones de demostración OpenAPI.
    • Código fuente para aplicaciones de demostración.
    • Demostración Spring Boot 2 Web MVC con OpenAPI 3.
    • Demostración Spring Boot 2 WebFlux con OpenAPI 3.
    • Demostración Spring Boot 2 WebFlux con puntos finales funcionales OpenAPI 3.
    • Demostración de Spring Boot 2 y Spring Hateoas con OpenAPI 3.
  • Integración de la biblioteca en un proyecto Spring Boot 3.x sin swagger-ui:
  • Manejo de errores para REST usando @ControllerAdvice
  • Agregar información de API y documentación de seguridad
  • soporte de spring-webflux con controladores anotados
• Expresiones de gratitud
  • Colaboradores
  • Soporte adicional

Documentación completa

Introducción

La biblioteca Java springdoc-openapi ayuda a automatizar la generación de documentación API utilizando proyectos Spring Boot. springdoc-openapi funciona examinando una aplicación en tiempo de ejecución para inferir la semántica de API basada en configuraciones de Spring, estructura de clases y varias anotaciones.

La biblioteca genera automáticamente documentación en páginas con formato JSON/YAML y HTML. La documentación generada se puede complementar mediante anotaciones swagger-api .

Esta biblioteca admite:

• API abierta 3
• Spring-boot v3 (Java 17 y Jakarta EE 9)
• JSR-303, específicamente para @NotNull, @Min, @Max y @Size.
• Swagger-ui
• OAuth 2
• Imágenes nativas de GraalVM

El siguiente vídeo presenta la Biblioteca:

• https://youtu.be/utRxyPfFlDw

Para compatibilidad con Spring-boot v3 , asegúrese de utilizar springdoc-openapi v2

Este es un proyecto comunitario, no mantenido por los contribuyentes de Spring Framework (Pivotal)

Empezando

Biblioteca para la integración de springdoc-openapi con spring-boot y swagger-ui

• Implementa automáticamente swagger-ui en una aplicación Spring Boot 3.x
• La documentación estará disponible en formato HTML, utilizando los archivos oficiales swagger-ui.
• La página de la interfaz de usuario de Swagger debería estar disponible en http://servidor: puerto/context-path/swagger-ui.html y la descripción de OpenAPI estará disponible en la siguiente URL para formato json: http://servidor:puerto/contexto -ruta/v3/api-docs
  • server : El nombre del servidor o IP
  • port : El puerto del servidor
  • context-path : la ruta de contexto de la aplicación.
• La documentación también puede estar disponible en formato yaml, en la siguiente ruta: /v3/api-docs.yaml
• Agregue la biblioteca springdoc-openapi-ui a la lista de dependencias de su proyecto (no se necesita configuración adicional):

experto

   < 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 '

• Este paso es opcional: para obtener una ruta personalizada de la documentación de swagger en formato HTML, agregue una propiedad springdoc personalizada en su archivo de configuración spring-boot:

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

Spring-boot con aplicaciones de demostración OpenAPI.

Código fuente para aplicaciones de demostración.

Demostración Spring Boot 3 Web MVC con OpenAPI 3.

Demostración Spring Boot 3 WebFlux con OpenAPI 3.

Demostración Spring Boot 3 WebFlux con puntos finales funcionales OpenAPI 3.

Demostración de Spring Boot 3 y Spring Cloud Function Web MVC.

Demostración de Spring Boot 3 y Spring Cloud Function WebFlux.

Demostración de Spring Boot 3 y Spring Cloud Gateway.

Integración de la biblioteca en un proyecto Spring Boot 3.x sin swagger-ui:

• La documentación estará disponible en la siguiente URL para formato json: http://servidor: puerto/context-path/v3/api-docs
  • server : El nombre del servidor o IP
  • port : El puerto del servidor
  • context-path : la ruta de contexto de la aplicación.
• La documentación también estará disponible en formato yaml, en la siguiente ruta: /v3/api-docs.yaml
• Agregue la biblioteca a la lista de dependencias de su proyecto. (No se necesita configuración adicional)

experto

   < 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 '

• Este paso es opcional: para obtener una ruta personalizada de la documentación de OpenAPI en formato Json, agregue una propiedad springdoc personalizada en su archivo de configuración spring-boot:

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

• Este paso es opcional: si desea deshabilitar los puntos finales springdoc-openapi , agregue una propiedad springdoc personalizada en su archivo de configuración spring-boot :

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

Manejo de errores para REST usando @ControllerAdvice

Para generar documentación automáticamente, asegúrese de que todos los métodos declaren las respuestas del código HTTP utilizando la anotación: @ResponseStatus.

Agregar información de API y documentación de seguridad

La biblioteca utiliza paquetes configurados automáticamente de la aplicación Spring-boot para buscar las siguientes anotaciones en Spring Beans: OpenAPIDefinition e Info. Estas anotaciones declaran información de la API: título, versión, licencia, seguridad, servidores, etiquetas, seguridad y documentos externos. Para un mejor rendimiento de la generación de documentación, declare las anotaciones @OpenAPIDefinition y @SecurityScheme dentro de un bean administrado por Spring.

soporte de spring-webflux con controladores anotados

• La documentación también puede estar disponible en formato yaml, en la siguiente ruta: /v3/api-docs.yaml
• Agregue la biblioteca a la lista de dependencias de su proyecto (no se necesita configuración adicional)

experto

   < 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 '

• Este paso es opcional: para obtener una ruta personalizada de la documentación de swagger en formato HTML, agregue una propiedad springdoc personalizada en su archivo de configuración spring-boot:

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

Las bibliotecas springdoc-openapi están alojadas en el repositorio central de maven. Se puede acceder a los artefactos en las siguientes ubicaciones:

Lanzamientos:

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

Instantáneas:

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

Expresiones de gratitud

Colaboradores

springdoc-openapi es relevante y se actualiza periódicamente debido a las valiosas contribuciones de sus colaboradores.

¡Gracias a todos por su apoyo!

Soporte adicional

• Equipo de Spring: gracias por su apoyo al compartir todos los recursos relevantes sobre los proyectos de Spring.
• JetBrains: muchas gracias por apoyar el proyecto springdoc-openapi.