En el mundo del desarrollo de software, la creación de servicios REST con Spring Boot es una tarea común. Sin embargo, estos servicios pueden volverse complejos rápidamente, con una variedad de métodos HTTP y parámetros. Además, estos servicios están destinados a ser consumidos por otros agentes, como aplicaciones Angular o incluso otras aplicaciones Java. Aquí es donde entra en juego la documentación de la API, y Open API es una excelente solución para este propósito. En este artículo veremos cómo integrar Open API en tu proyecto Spring Boot
¿Qué es Open API?
Open API es una librería Java que facilita la documentación de nuestras APIs. Genera automáticamente documentación en formatos JSON/YAML y HTML utilizando Swagger. Veamos cómo integrar Open API en tu proyecto Spring Boot.
Configurando Open API en tu Proyecto Spring Boot
Para comenzar, vamos a utilizar el proyecto que creamos en un entrada anterior. Este proyecto servirá como base para nuestro nuevo proyecto.
Primero, clonamos el proyecto desde GitHub con el siguiente comando:
$ git clone https://github.com/secdevoops/spring-boot-hello-world.git
Luego, renombramos la carpeta del proyecto y eliminamos la carpeta .git para poder generar otro proyecto git distinto:
$ mv spring-boot-hello-world spring-boot-open-api
$ cd spring-boot-open-api/
$ rm -fr .git
A continuación, editamos el archivo pom.xml para cambiar el artifactId y tener un artefacto distinto:
<artifactId>spring-boot-open-api</artifactId>
Añadiendo las Dependencias Necesarias
Una vez que tenemos el proyecto importado, editamos nuestro pom.xml para añadir las dependencias necesarias. Dentro de la etiqueta <properties>, añadimos una nueva propiedad para la versión de open-api:
<springdoc-openapi-ui.version>1.2.32</springdoc-openapi-ui.version>
Y dentro de la etiqueta <dependencies>, añadimos la siguiente dependencia:
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>${springdoc-openapi-ui.version}</version>
</dependency>
Con esto, una vez que levantemos nuestra aplicación, podremos acceder a http://localhost:8080/swagger-ui.html para ver nuestros servicios REST.
Seguridad en Producción
Es importante tener en cuenta que, en un entorno de producción, no queremos tener accesible Open Api con todos nuestros servicios documentados. Para evitar esto, podemos utilizar los perfiles de Maven de manera que la dependencia de Open Api solo la añadamos en un perfil de desarrollo y tener otro para producción donde no añadamos dicha librería.
Para esto, podemos añadir lo siguiente en nuestro pom.xml:
<profiles>
<profile>
<id>dev</id>
<activation>
<activeByDefault>true</activeByDefault>
</activation>
<dependencies>
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>${springdoc-openapi-ui.version}</version>
</dependency>
</dependencies>
</profile>
<profile>
<id>prod</id>
</profile>
</profiles>
De esta manera, por defecto tenemos activado nuestro perfil de desarrollo con la dependencia de Open Api, y a la hora de construir nuestra aplicación para el entorno de producción, podemos indicar que queremos usar el perfil con id prod.
Desde nuestra terminal, podríamos empaquetar nuestra aplicación con el comando:
$ mvn package -P prod
Autenticación con Spring Security
Si añadimos autenticación con Spring Security a nuestros servicios, desde Swagger no podremos añadir la cabecera Authorization necesaria para enviar el token JWT en nuestras peticiones.
Para poder hacer eso, debemos añadir una clase que sobreescriba la configuración de Open Api.
@Configuration
public class OpenApiConfig {
@Bean
public OpenAPI customOpenAPI() {
final String securitySchemeName = "bearerAuth";
final String apiTitle = String.format("%s API", "SecDevOops");
return new OpenAPI()
.addSecurityItem(new SecurityRequirement().addList(securitySchemeName))
.components(
new Components()
.addSecuritySchemes(securitySchemeName,
new SecurityScheme()
.name(securitySchemeName)
.type(SecurityScheme.Type.HTTP)
.scheme("bearer")
.bearerFormat("JWT")
)
)
.info(new Info().title(apiTitle).version("1.0"));
}
}
Con esto, ya nos aparecerá una opción en Swagger para poder añadir nuestro token pinchando sobre Authorize y añadir nuestro token.
Una vez que que hemos añadido el token y le damos a Authorize, nuestro token irá ya en todas las peticiones que hagamos desde Swagger. Si queremos dejar de usarlo, no tenemos más que entrar de nuevo y hacer Logout.