Ejemplo sencillo openapi rest swagger

De ChuWiki

Openapi es una especificación en la que por medio de un fichero en formato json o yaml especificamos y documentamos web services REST. Luego hay herramientas que son capaces de generar el código en diversos lenguajes de programación tanto de cliente del servicio web como del servidor.

Swagger simplifica el proceso de creación de estos ficheros json o yaml. Crear el fichero desde cero o con ayuda de un editor especializado requiere conocer la especificación y es un trabajo pesado. Con Swagger, podemos generar nuestro web service REST con Java y luego, a partir del código, generar el fichero openapi.

Veamos un ejemplo que tienes en swagger-example

Creación del web service REST en Java[editar]

Primero creamos el web service REST en Java. Por facilidad usamos Spring Boot. Tienes detalles de cómo hacerlo en Servicio Web Restful con Spring Boot. Para nuestro ejemplo, no vamos a usar el código de ese enlace, sino otro similar en swagger-example. No daremos aquí mucho detalle puesto que aquí vamos a ver cómo usar swagger, no cómo crear el web service.

Vamos a usar Maven, así que en el fichero pom.xml ponemos estas dos depenendencias

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
            <version>1.6.8</version>
        </dependency>

La primera es la dependencia de Spring Boot necesaria para poder crear los web service. La segunda publicará de forma automática en determinadas URL los ficheros openapi y la documentación swagger asociada. Lo hará cuando nuestra aplicación arranque y publique los web service REST en la URL que indiquemos.

Es decir, si nuestros web services una vez arrancados están en las URL http://localhost:8080/greetings, el fichero openapi estará por defecto disponible en http://localhost:8080/v3/api-docs mientras que la documentación swagger estará en http://localhost:8080/swagger-ui/index.html

En cuanto a las clases Java para web service, en este ejemplo creamos dos. Una es WebService.java y la otra es WebService2.java. Ningún motivo especial, solo por tener una simple cuyos parámetros son solo String y otra un poco más compleja que maneje una estructura de datos.

Las clases van anotadas con la anotación spring @RestController para que spring sepa que tiene que levantarlos como servicios web. Los métodos van anotados con @GetMapping('path = "/greeting"') y @PostMapping(path = "/data") para:

  • El primero es una petición GET cuya URL será la URL base más "/gretting", es decir http://localhost:8080/greeting.
  • El segundo es una petición POST cuya URL será la URL base más "/data", es decir http://localhost:8080/data/

En código, sólo las anotaciones

@RestController
public class WebService {
    @GetMapping(path = "/greeting")
    public String greeting(
            String name) {
        return "Hello "+name;
    }
}


@RestController
public class WebService2 {
    @PostMapping(path = "/data")
    public Data greeting2(Data data) {
        data.setValue(data.getValue()+1);
        data.setString(data.getString()+".....?");
        data.setDate(new Date());
        return data;
    }
}

Data es una simple estructura de datos con tres campos: un entero, una fecha Date y un string. Puedes ver el código en Data.java

Acceso a openapi y documentación swagger[editar]

Si arrancamos la aplicación, tendremos openapi y documentación swagger disponibles en las siguientes URL (fíjate en la barra del navegador en la foto, son las que hemos mencionado antes)

En las imágenes hay más información de la que hemos puesto hasta ahora, como el título "Open API chuidiang example". No te preocupes, vemos ahora como añadir toda esta información adicional.

En la primera imagen ves el fichero json que está en la URL correspondiente. Este fichero json permite, con otras herramientas que veremos en otro artículo, generar código java o en otros lenguajes, tanto para el servidor que levanta el web service, como para los clientes que quieren llamarlo. Recuerda que la forma correcta, no para vagos, sería generar el fichero openapi antes de liarse a programar, de ahí que existan herramientas que también generan el código del servidor a partir del fichero json.

En la segunda imagen ves la documentación swagger. Esta documentación el formato html bonito, que se puede ver en el navegador. Veremos algo más de detalle después.

Anotaciones Swagger[editar]

Con las anotaciones de Spring no hay información suficiente para generar todo lo que pide open api como obligatorio (por ejemplo, la versión que damos a nuestro web service), así que aquí viene Swagger en nuestra ayuda. Swagger tiene anotaciones adicionales a las de spring que nos permite añadir todo esto que es obligatorio en la especificación openapi, como añadir información adicional útil que no se contempla con las anotaciones spring.

No vamos a ver aquí todas las anotaciones y para qué sirven, pero sí algunas básicas.

Campos obligatorios de la documentación OpenAPI[editar]

En la especificación open API, un documento open API es un openAPI Object y tiene dos campos obligatorios:

  • Un string "openapi" con el número de versión de "openapi" que estamos generando/usando. Debe ser uno de los números que exista: 1.2, 2.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.1.0. Se supone que el resto del documento seguirá la especificación correspondiente a la versión que pongamos aquí
  • Una estructura info object que tiene a su vez dos campos obligatorios:
    • Un string título de nuestro documento, ponemos lo que más nos guste como título de nuestro documento
    • Un string versión de nuestro documento, ponemos lo que más nos guste como versión de nuestro documento.

¿Cómo ponemos todo esto en nuestro código java? Tenemos dos opciones

  • Usar anotaciones Swagger
  • Usando la configuración de Srping, crear un bean OpenAPI.

Veamos ambos métodos, que son alternativos, no necesitas poner los dos. O uno, u otro.

Con anotaciones, en la clase main de Spring Boot, o cualquier otra clase que esté en algún paquete que Spring Boot escanee en busca de antoaciones, ponemos

@OpenAPIDefinition(info = @Info(
        title = "Open API chuidiang example",
        version = "1.0"
))
@SpringBootApplication
public class Main {
    public static void main(String[] args) {
        SpringApplication.run(Main.class, args);
    }
}

La anotación es @OpenAPIDefinition. No necesitamos poner la versión de openAPI, puesto que la herramienta springdoc-openapi-ui la generará automáticamente de acuerdo a la versión que esté usando. Si miras el enlace, verás en el apartado de properties que puedes configurar que versión usar, por defecto la 3.0.1

Si necesitamos poner @Info dentro de @OpenAPIDefinition y dentro de esa estructura, el título de nuestro documento y su versión (que no es la versión de la especificación openAPI, sino la versión de nuestro documento concreto que estamos generando).

La otra opción es usando un bean de configuración de Spring Boot. El código de ejemplo sería el siguiente

@Configuration
public class OpenAPIConfig {
    /**
     * Para la cabecera del documento generado par openapi / swagger.
     * Datos generales del servidor, desarrolladores, contacto, etc.
     * @return
     */
    @Bean
    public OpenAPI getOpenApiDefinition(){
        return new OpenAPI()
            .info(new Info()
                .title("Open API chuidiang example")
                .version("1.0")
            );
    }
}

Vemos que básicamente es la misma info que en la anotación, pero hecho de otra forma.

Tanto de una forma como de otra, podemos poner más info adicional, no obligatoria, que openAPI permita y que pueda ser útil mostrar en la documentación, como servidores donde está levantado el Web Service, URL de documentación del proyecto, contacto de los desarrolladores, etc, etc.

En documentación saldría así

Ves el título, en pequeñito a su lado la versión 1.0 y el servidor en el que está disponible el web service, que como no hemos puesto nada, dice que es "generated" por la herramienta.

Documentación OpenAPI de los web services[editar]

Solo con las anotaciones spring la documentación de los web services queda un poco pobre. Solo qué metodos hay (URL), que parámetros admite y qué devuelve. Pero ninguna explicación, nombre amigable, etc. Hay anotaciones Swagger que nos permiten ampliar y dejar más legible para humanos la documentación. Vamos a ver sólo tres de ellas: la que explica qué hace el web service, la que explica qué hace un método concreto del web service y la que explica un parámetro del método.

En código, algo como esto

@RestController
@Tag(name="Saludos", description = "Metodos de saludo")
public class WebService {
    @GetMapping(path = "/greeting")
    @Operation(
            summary = "saluda a alguien",
            description = "Se le pasa un nombre y devuelve saludo a ese nombre"
    )
    public String greeting(
            @Parameter(
                    description = "A quien saludar"
            )
            String name) {
        return "Hello "+name;
    }
}

A nivel de clase, la anotación @Tag nos permite dar un nombre legible "saludos" al web service y una descripción de dicho web service.

En cuanto al método concreto, la anotación @Operation nos permite poner algo de documentación adicional. En concreto, summary sería un descripción corta y description sería la detallada. La anotación @Parameter en el parámetro también permite poner una descripción del mismo. La siguiente imagen muestra el resultado

Ves que aparece al principio la información que hemos puesto en @Tag, que aparece el web service "greeting". Luego en el detalle del web service no te costará encontrar todos los textos que hemos ido poniendo.

Probar nuestros Web Services[editar]

Fíjate que hay un botón "Try it out". Pulsando este botón podremos cambiar los valores del parámetro de entrada y luego, pulsando el botón "execute" que nos aparecerá, podremos ver el resultado de la llamada

Ultimos puntos[editar]

La documentación openAPI y Swagger son mucho más complejos y tienen muchas más posibilidades de lo mencionado aquí. Sirva este tutorial solo como una forma de entender algunos conceptos básicos de openAPI y Swagger y una forma rápida de empezar, aunque no sea la más metódica.