Frameworks

Importancia de documentar una API

La documentación de una API es muy importante, ya que una API que no esté documentada, seguramente sea una API difícil de utilizar, por dos motivos:

• No todo el mundo va a entender por REST lo mismo. Existe un modelo de madurez propuesto por un autor, en el que podemos ver en la práctica como en algunos momentos no todo encuentra en el mismo estadio de madurez dentro de gran parte de las API REST.

• En ocasiones, se implementan reglas de validación que nos obligan a utilizar tipos de dato concretos o algún formato excesivamente concreto, que es bueno conocer.

Cómo crear esta documentación

Tenemos varias alternativas para crear la documentación e una API REST. Una de ellas es utilizando Spring REST Docs, una propuesta válida y propuesta por Spring.

Pero en nuestro caso, os vamos a mostrar cómo hacerlo con Swagger y Swagger UI, que nos permiten hacerlo de una forma muy sencilla.

Qué es Swagger

Swagger es un framework de código abierto y respaldado por un gran ecosistema de herramientas, que como desarrolladores nos ayudan a diseñar, construir, documentar y consumir un servicio RESTful.

Una de las más utilizadas es Swagger UI Tool, que nos va a permitir tener una interfaz de usuario que nos muestre para una API las peticiones y la documentación de las mismas.

Swagger será, dentro de todo el abanico de herramientas que tiene, una serie de reglas, especificaciones y herramientas que nos ayudan a documentar nuestra API.

Qué es SpringFox

SpringFox es un conjunto de librerías que nos permiten generar automáticamente la documentación de nuestra API, que además es capaz de generar esta documentación en formato de Swagger.

Aprovecharemos que SpringFox genera el fichero swagger.json automáticamente, ya que partir del mismo podremos utilizar la aplicación Swagger UI.

Adicionalmente tenemos algunas clases y anotaciones para poder gestionar la aplicación desde Spring.

Swagger + SpringFox

Para utilizar Swagger y SpringFox necesitamos:

• Incluir un par de dependencias en nuestro proyecto:

<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
</dependency>
<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
</dependency>

• Hacer alguna configuración básica, como por ejemplo la siguiente:

@Configuration @EnableSwagger2
public class SwaggerConfig {

            @Bean
            public Docket api() {
                        return new Docket(DocumentationType.SWAGGER_2)
                                    .select()
                                    .apis(
                                            RequestHandlerSelectors
                                            .basePackage(“com.openwebinars.net.rest.controller”))
                                    .paths(PathSelectors.any())
                                    .build();
                }
}

Todo esto es muy customizable, aunque en el ejemplo lo vamos a hacer bastante sencillo, y a partir de aquí nos ayudaría a generar toda nuestra documentación.

Ejemplo práctico

En el video puedes ver cómo se configura Swagger para documentar una API REST desarrollada con Spring Boot.

Podrás seguir paso a paso todo el proceso, desde la inclusión de las dependencias hasta la verificación de todo el proceso para comprobar que funciona correctamente.