OpenAPI 3 con Spring Boot

Cuando trabajamos con microservicios es muy normal crear un contrato primero adoptando la aproximación API First, para la comunicación y acceso a nuestros servicios. Para estos casos OpenAPI 3 con Spring Boot es una buena aproximación, ya que además existen librerías que nos generarán las interfaces para facilitarnos la implementación.

¿Qué es OpenAPI?

La especificación OpenAPI, que en un principio fue conocida como Swagger especificación, es una especificación concreta humano-máquina que describe una interfaz, productor, consumidor y visualización para servicios web RESTful; por lo convierte a OpenAPI 3 en una buena herramienta para hacer desarrollos con Spring Boot.

La actual versión de OpenAPI es la 3 y liberada en 2017. En este artículo vamos a ver un ejemplo de como a partir de una definición de OpenAPI 3, generamos los objetos y los controladores en una aplicación Spring Boot.

Usando OpenAPI 3

Dependencias de OpenAPI3 en una aplicación Spring Boot

A continuación se detallan las dependencias y plugin necesarios que hay que añadir a tu fichero pom.xml:

    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>${springfox-version}</version>
    </dependency>
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>${springfox-version}</version>
    </dependency>

Las librerías anteriores que son de springfox nos aporta documentación automatizada de API JSON para API construidas que construimos con Spring. Luego veremos como podemos visualizar la interfaz que nos proporciona swagger-ui para poder trabajar con el API.

 <plugin>
        <groupId>org.openapitools</groupId>
        <artifactId>openapi-generator-maven-plugin</artifactId>
        <version>3.3.4</version>
        <executions>
          <execution>
            <id>spring-boot-api</id>
            <goals>
              <goal>generate</goal>
            </goals>
            <configuration>
              <inputSpec>${project.basedir}/src/main/resources/api.yaml</inputSpec>
              <generatorName>spring</generatorName>
              <output>./</output>
              <configOptions>
                <sourceFolder>src/main/java</sourceFolder>
                <java8>true</java8>
                <interfaceOnly>true</interfaceOnly>
              </configOptions>
              <modelPackage>${folder-to-generate-model}</modelPackage>
              <apiPackage>${folder-to-generate-controller}</apiPackage>
              <modelNameSuffix>Dto</modelNameSuffix>
              <generateApiDocumentation>false</generateApiDocumentation>
              <generateModelDocumentation>false</generateModelDocumentation>
            </configuration>
          </execution>
        </executions>
      </plugin>

El plugin anterior deberá ser añadido dentro del pom.xml en la parte de plugins. Este plugin nos va a permitir generar los DTO y los controladores desde la especificación del API.

Añadiendo OpenAPI 3 a nuestra aplicación Spring Boot

Lo primero que vamos a hacer es configurar nuestra aplicación Spring Boot para que pueda utilizar OpenAPI 3. Para ello, vamos a activarlo mediate la anotación @EnableSwagger2; y crear una clase de configuración para dar información a nuestra API, como el título o descripción, y que sea la ubicación de nuestros controladores.

@Configuration
@RequiredArgsConstructor
@EnableSwagger2
public class SwaggerConfig {

  private final BuildProperties buildProperties;

  @Bean
  public Docket docketConfig() {
    return new Docket(DocumentationType.SWAGGER_2)
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.refactorizando.openapi.infrastructure.rest.spring.resource"))
        .build().apiInfo(apiInfo());
  }

  private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
        .title(buildProperties.getName())
        .version(buildProperties.getVersion())
        .build();
  }

}

La clase anterior será la encargada de la configuración de OpenApi 3. Como hemos comentado anteriormente, hemos activado añadido la anotación @EnableSwagger 2 , y creado su configuración; por un lado creamos un Bean en el que le añadimos información al api (apiInfo()) y establecemos el paquete donde se encuentran los controladores. Aunque sea @EnableSwagger2 es totalmente válido para openAPI 3.

Definición de API para formato OpenAPI 3

Para que Spring reconozca nuestro fichero API.yml en donde definimos nuestra API, vamos a añadir este fichero dentro de la carpeta resources.

A continuación mostramos el API.yml que se va a ejecutar en el proyecto.

openapi: "3.0.0"
info:
  description: "Bank API"
  version: "1.0.0"
  title: "Bank API"
  contact:
    email: "refactorizando.web@gmail.com"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
servers:
  - url: http://localhost:8000/
    description: "local host"
paths:
  /users:
    get:
      tags:
        - "user"
      summary: "Find a collection of users"
      operationId: "getUsers"
      responses:
        200:
          description: "Retrieve users"
          content:
            application/json:
              schema:
                type: "array"
                items:
                  $ref: "#/components/schemas/User"
        400:
          description: "BadRequest"
          content:
            application/json:
              schema:
                type: "object"
                $ref: "#/components/schemas/Error"
        500:
          description: "Internal server error"
          content:
            application/json:
              schema:
                type: "object"
                $ref: "#/components/schemas/Error"
        503:
          description: "Service unavailable"
          content:
            application/json:
              schema:
                type: "object"
                $ref: "#/components/schemas/Error"


components:
  schemas:
    User:
      type: "object"
      required:
        - "id"
      properties:
        id:
          type: "integer"
          format: "int64"
        name:
          type: "string"
          example: "Francisco Martín"
        address:
          type: "string"
          example: "Avendia de la zarzuela"
        phone:
          type: "string"
          example: "+00 6656545"
        postalCode:
          type: "string"
          example: "28007"


    Error:
      type: "object"
      properties:
        code:
          type: "integer"
          format: "32"
        message:
          type: "string"
        description:
          type: "string"

El ejemplo anterior, aunque muy básico, nos bastará para ver como crear a partir de una especificación OpenAPI un controlador con Spring Boot. Una vez definido el API.yaml, procederemos a realizar un package o un install de maven en nuestro proyecto, y veremos como en la carpeta definida en apiPackage se habrá generado el controlador, y en la carpeta definida en modelPackage los dto y ya podremos seguir desarrollando nuestra aplicación Spring Boot.

No te olvides de añadir en el fichero .openapi-generator-ignore, aquellos fichero que no quieres que se modifiquen por el plugin de openAPI; por ejemplo añadir pom.xml o Readme.md

Para ver las dependencias y como se puede generar el código pulsando aquí puedes ver el código.

Conclusión

En este artículo hemos visto como Spring Boot nos puede ayudar a crear a partir de un API desarrollada con OpenAPI 3, los controladores, los Dtos y la documentación necesaria.