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 *