Documentación de la API REST de Java con Swagger2

    Introducción

    En este artículo, profundizaremos en Marco de Swagger. Usaremos Swagger2 para diseñar, construir y documentar un Bota de Spring API RESTful y IU de Swagger para observar nuestros puntos finales y probarlos.

    ¿Qué es Swagger?

    Swagger es la herramienta más utilizada para crear API que cumplan con la Especificación de OpenAPI (OEA).

    Swagger en sí es un conjunto de herramientas de código abierto creadas alrededor de la OEA que pueden ayudarlo a diseñar, construir, documentar y generar los documentos de la API REST para los servicios web RESTful.

    Las herramientas Swagger más destacadas son:

    • Editor de Swagger – editor basado en navegador donde puede escribir especificaciones de OpenAPI
    • IU de Swagger – presenta las especificaciones de OpenAPI como documentación API interactiva
    • Swagger Codegen – genera stubs de servidor y bibliotecas cliente a partir de una especificación de OpenAPI

    Swagger2 es una extensión de Swagger a nuevas tecnologías y protocolos más allá de HTTP.

    Construyendo una aplicación

    La integración de Swagger2 en una aplicación Spring Boot es bastante rápida y fácil con la ayuda de algunas herramientas que ya usamos día tras día.

    La forma más sencilla de comenzar con un proyecto Spring Boot esqueleto, como siempre, es usar Spring Initializr.

    Seleccione su versión preferida de Spring Boot y generela como un proyecto de Maven y ¡listo!

    Para habilitar Swagger2 en sí, deberá agregar un par de dependencias a su pom.xml archivo:

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

    Con nuestro proyecto completamente configurado y nuestras dependencias bajo control, podemos seguir adelante y crear un punto final REST simple que expondremos en la documentación más adelante:

    @RestController
    @RequestMapping("/v1/hello")
    public class HelloResource {
    
        @GetMapping
        public String hello() {
            return "Hello World";
        }
    
        @PostMapping("/post")
        public String helloPost(@RequestBody String hello) {
            return hello;
        }
    
        @PutMapping("/put")
        public String helloPut(@RequestBody String hello) {
            return hello;
        }
    }
    

    Después de esto, sigamos adelante y creemos un punto final REST más: UserResource:

    @RestController
    @RequestMapping("/v1/user")
    public class UserResource {
    
    @GetMapping
    public List<User> getUsers() {
        return Arrays.asList(
            new User("John", 3000),
            new User("Kevin", 2000)
        );
    }
    
    @GetMapping("/{userName}")
    public User getUser(@PathVariable("userName") String userName) {
        return new User(userName, 2000);
    }
    

    Ambas clases se basan en la User modelo:

    private class User {
    
        private String userName;
        private Integer salary;
    
        // constructor, getters and setters
    }
    

    Habilitando Swagger2

    Ha llegado el momento de habilitar Swagger2 en nuestra aplicación definiendo una clase de configuración para ella.

    La clase de configuración debe anotarse con @Configuration – la anotación estándar de Spring, y @EnableSwagger2 anotaciones para habilitar el marco para su aplicación Spring Boot.

    El orden de estas anotaciones no es importante:

    @EnableSwagger2
    @Configuration
    public class Swagger2Config {
    
        @Bean
        public Docket productApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.demo.resource"))
                .paths(regex("/v1.*"))
                .build();
        }
    }
    

    Definiremos un Bean llamado Docket en la clase de configuración para este propósito.

    Docket es un constructor que pretende ser la interfaz principal en el swagger-springmvc marco de referencia. Proporciona valores predeterminados sensibles y métodos convenientes para la configuración.

    Una vez definido el bean Docket, llamando a su select() El método devuelve una instancia de ApiSelectorBuilder, que proporciona control sobre los puntos finales expuestos por Swagger.

    También podemos definir un paquete base para nuestras clases de API REST si lo deseamos, usando RequestHandlerSelectors.basePackage(). Escaneará el paquete base y creará API para todas las clases dentro de él.

    Por otro lado, podemos usar RequestHandlerSelectors.any() para generar documentación para todos los paquetes.

    En nuestro caso, es el com.demo.resource paquete, donde definimos el HelloResource y UserResource clases.

    los paths() El método define además para qué rutas en nuestras API queremos crear documentación. Todos nuestros puntos finales tienen «/ v1», por lo que en nuestro caso incluye todos los puntos finales. Sin embargo, puede que no siempre sea así.

    Si desea incluir todos los puntos finales, puede hacerlo fácilmente utilizando PathSelectors.any().

    IU de Swagger

    Usemos la interfaz de usuario de Swagger para observar todos nuestros puntos finales REST que creó Swagger.

    Para utilizar la interfaz de usuario de Swagger, debemos agregar una dependencia a nuestro pom.xml archivo:

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

    Ahora navega a localhost:8080/swagger-ui.html. Esta es la URL donde podemos observar todos los puntos finales de descanso que creó Swagger:

    Como puede ver, nuestros dos puntos finales están aquí: hello-resource y user-resource, con sus respectivos métodos dentro. Los nombres de los métodos se definen a la derecha, como puede ver.

    Podemos usar esta interfaz de usuario para probar nuestros puntos finales:

    • Haga clic en HelloResource y expandir GET/v1/hello
    • Haga clic en la llamada de descanso Try it out botón

    Seremos recibidos con el cuerpo de respuesta «Hola mundo» y el código de respuesta 200, lo que significa que está funcionando según lo previsto.

    Igual que para el GET/v1/user de la clase UserResource:

    Seremos recibidos con la información relevante para el usuario que creamos antes.

    Personalización de Swagger2

    A veces, las empresas y los equipos necesitan personalizar el comportamiento de Swagger2, agregando mensajes y operaciones personalizados para adaptar el uso del marco a sus propias necesidades.

    Para hacer esto, necesitamos anular la metainformación del marco con ApiInfo.

    El constructor de ApiInfo espera:

    • String title
    • String description
    • String version
    • String termsOfServiceUrl
    • new Contact(contactName, "", "")
    • String license
    • String licenseUrl

    Si no desea definir ninguno de estos, puede ingresar null y ese campo no se mostrará en la interfaz de usuario:

    @EnableSwagger2
    @Configuration
    public class SwaggerConfig {
    
        @Bean
        public Docket productApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.demo.resource"))
                .paths(regex("/v1.*"))
                .build()
                .apiInfo(metaInfo());
        }
    
        private ApiInfo metaInfo() {
    
            ApiInfo apiInfo = new ApiInfo(
                "Spring Boot Swagger2 Example API",
                null,
                "1.0",
                "Terms of Service",
                new Contact("Your Name or Team", null,
                    null),
                "Apache License Version 2.0",
                "https://www.apache.org/licenses/"
            );
    
            return apiInfo;
        }
    }
    

    Podemos anular los nombres de los métodos con anotaciones.

    los @ApiOperation La anotación nos permite anular el punto final y su tipo de respuesta. Swagger2 también permite anular los mensajes de respuesta predeterminados de HTTP métodos.

    Puedes usar el @ApiResponse anotación para documentar otras respuestas, además del habitual HTTP 200 OK:

    @ApiOperation(value = "Returns Hello World", description = "shows hello world")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "The request has succeeded or (your message)"),
            @ApiResponse(code = 401, message = "The request requires user authentication or (your message)"),
            @ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden or (your message)"),
            @ApiResponse(code = 404, message = "The server has not found anything matching the Request-URI or (your message)")
    

    Echemos un vistazo a la interfaz de usuario:

    Al expandirse hello-resource podemos ver que el lado derecho de la documentación se actualizó. Además, los mensajes de respuesta se actualizaron con el código que proporcionamos y el tipo de retorno del @Api anotación a nivel de clase.

    Propiedades del modelo

    Swagger2 nos proporciona un conjunto de anotaciones para manipular modelos con mucho control:

    • @ApiModel: nos permite manipular metadatos de un modelo
    • @ApiModelProperty: nos permite controlar las definiciones y operaciones específicas de Swagger (valores permitidos, notas, filtrado)

    Necesitaremos actualizar nuestro UserResource controlador con el @Api anotación a nivel de clase.

    En Swagger2, esta anotación se usa para aplicar definiciones a todas las operaciones definidas bajo ella, a diferencia de su uso en versiones anteriores, donde declaraba recursos:

    @RestController
    @RequestMapping("/v1/user")
    @Api(value = "User Resource REST Endpoint", description = "Shows the user info")
    public class UserResource {
    
        @GetMapping
        public List<User> getUsers() {
    
            return Arrays.asList(
                new User("John", 2000),
                new User("Kevin", 1000)
            );
        }
    
        @GetMapping("/{userName}")
        public User getUser(@PathVariable("userName") String userName) {
            return new User(userName, 1000);
        }
    

    Después de actualizar la API, actualice también el modelo:

    @ApiModel
    private class User {
    
        @ApiModelProperty(notes = "name of the user")
        private String userName;
    
        @ApiModelProperty(notes = "salary of the user")
        private Integer salary;
    
        @ApiModelProperty(allowableValues = "active, inactive, banned")
        private String status;
    
        // constructor, getters and setters
    }
    

    Hay una amplia gama de cosas que puede definir usando @ApiModelProperty. Para obtener más información y una lista de métodos, visite la documentación oficial.

    En expansión GET/v1/user luego haciendo clic en el Model propiedad, podemos notar las descripciones en cada campo.

    El «Valor de ejemplo» muestra solo los valores predeterminados.

    Conclusión

    Cada día, las empresas y las personas comienzan a utilizar Swagger como su herramienta de elección para exponer las API REST a terceros.

    Utilizando las herramientas de Swagger, puede generar código basado en la documentación de una API, así como crear documentación atractiva e interactiva. Esto ahorra tiempo y esfuerzo y ofrece un estándar para que las personas trabajen.

     

    Etiquetas:

    Deja una respuesta

    Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *