Swagger en Spring Boot

Swagger en Spring Boot

  marzo 06, 2020    Reynaldo Claros

---

La documentación de una API es muy importante, sobre todo cuando separamos el Backend y Frontend, el que hace las tareas de Frontend, facilmente puede probarlos, sin necesidad de estar consultando con el responsable del Backend.

Para ello, vamos a utilizar Spring boot, y realizar la configuración e instalación.



Nos movemos a https://start.spring.io/ para crear nuestro proyecto en spring.



La dependencia que necesitamos es Spring Web.





Ahora vamos a configurar el pom.xml con las dependencias necesarias.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.2.5.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.dev.api</groupId>
    <artifactId>api-docs</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>api-docs</name>
    <description>Demo project for Spring Boot</description>

    <properties>
        <java.version>1.8</java.version>
        <springfox.swagger.version>2.9.2</springfox.swagger.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${springfox.swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${springfox.swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
            <exclusions>
                <exclusion>
                    <groupId>org.junit.vintage</groupId>
                    <artifactId>junit-vintage-engine</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

Como podemos ver. las dependencias necesarias son:

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

 Ahora que nuestro proyecto ya tiene instalado las dependencias, vamos a configurar swagger a nivel de código.



Tenemos que crear una clase llamada: SwaggerConfiguracion.java con el siguiente contenido.

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
    public static final String AUTHORIZATION_HEADER = "Authorization";
    public static final String DEFAULT_INCLUDE_PATTERN = "/api/.*";
    ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("API")
                .description("Rest Service")
                .termsOfServiceUrl("").version("1.0.0").contact(new Contact("DEV", "http://claros-dev.blogspot.com/", "reyiclaros@gmail.com")).build();
    }
    @Bean
    public Docket configureControllerPackageAndConvertors() {
        return new Docket(DocumentationType.SWAGGER_2).select()
                .apis(RequestHandlerSelectors.basePackage("com.dev.api.apidocs.controller"))
                .build()
                .forCodeGeneration(true)
                .genericModelSubstitutes(ResponseEntity.class)
                .ignoredParameterTypes(Pageable.class)
                .ignoredParameterTypes(java.sql.Date.class)
                .directModelSubstitute(java.time.LocalDate.class, java.sql.Date.class)
                .directModelSubstitute(java.time.ZonedDateTime.class, Date.class)
                .directModelSubstitute(java.time.LocalDateTime.class, Date.class)
                .securityContexts(Lists.newArrayList(securityContext()))
                .securitySchemes(Lists.newArrayList(apiKey()))
                .apiInfo(apiInfo())
                .useDefaultResponseMessages(false);

    }
    private ApiKey apiKey() {
        return new ApiKey("JWT", AUTHORIZATION_HEADER, "header");
    }
    private SecurityContext securityContext() {
        return SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.regex(DEFAULT_INCLUDE_PATTERN))
                .build();
    }
    List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return Lists.newArrayList(new SecurityReference("JWT", authorizationScopes));
    }
}

El resultado los vemos:

Adicionalmente nuestra configuración inclute "Autorize" para agregar un token y enviar en nuestras peticiones, tal como lo vemos en las siguientes imagenes.

Como podemos ver. la configuración de Swagger es muy simple.



Recuerda que como Backend es indispensable documentar nuestras APIS, para fascilitar el desarrollo en el equipo.



El codigo del proyecto lo pueden descargar en GitHub



Saludos.