Características do Swagger2

• Gera autoamticamente documentação de APIs diretamente a partir do código-fonte.
• A documentação é atualizada automaticamente conforme as alterações nos endpoints.
• Oferece uma interface visual intuitiva e interativa para exploração das APIs.
• Permite testar endpoints diretamente pela interface, facilitando a validação funcional.

Implementação do Swagger2 em Projeto Spring Boot

1. Adição das dependências no Maven

<?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.4.4</version>
        <relativePath/>
    </parent>

    <groupId>com.exemplo</groupId>
    <artifactId>api-documentation-demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>

    <properties>
        <java.version>1.8</java.version>
        <swagger.version>2.9.2</swagger.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <scope>provided</scope>
        </dependency>

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

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

2. Classe de configuração do Swagger

@Configuration
@EnableSwagger2
public class OpenApiConfig {

    @Bean
    public Docket apiDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.exemplo.api"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiMetadata());
    }

    private ApiInfo apiMetadata() {
        return new ApiInfoBuilder()
                .title("Documentação da API de Usuários")
                .description("API REST para gerenciamento de usuários")
                .version("1.0.0")
                .contact(new Contact("Equipe de Desenvolvimento", "", "dev@example.com"))
                .build();
    }
}

3. Ativação no arquivo principal da aplicação

@SpringBootApplication
public class ApiDocumentationApplication {
    public static void main(String[] args) {
        SpringApplication.run(ApiDocumentationApplication.class, args);
    }
}

4. Classe de domínio com anotações do Swagger

@Data
@ApiModel(description = "Representa um usuário no sistema")
public class Usuario {

    @ApiModelProperty(example = "1001", value = "Identificador único do usuário")
    private Long id;

    @ApiModelProperty(example = "João Silva", value = "Nome completo do usuário")
    private String nome;

    @ApiModelProperty(example = "30", value = "Idade do usuário")
    private Integer idade;

    @ApiModelProperty(example = "true", value = "Indica se o usuário está ativo")
    private Boolean ativo;

    @ApiModelProperty(value = "Observações adicionais sobre o usuário")
    private String observacoes;
}

5. Controlador com anotações para documentação

@RestController
@RequestMapping("/v1/usuarios")
@Api(tags = "Operações com Usuários", description = "Endpoints para gerenciamento de usuários")
public class UsuarioController {

    @GetMapping("/{id}")
    @ApiOperation("Recupera um usuário pelo seu identificador único")
    public Usuario obterUsuario(
            @ApiParam(value = "ID do usuário", required = true, example = "1001")
            @PathVariable Long id) {
        return new Usuario();
    }
}

6. Arquivo de propriedades da aplicação

server.port=8080

7. Acesso à interface de documentação

Após iniciar a aplicação, acesse:

http://localhost:8080/swagger-ui.html

Anotações mais utilizadas do Swagger2

• @Api: Documenta a finalidade geral de um controlador REST.
• @ApiOperation: Descreve o propósito de um endpoint específico.
• @ApiParam: Fornece detalhes sobre um parâmetro de método (ex.: path, query).
• @ApiModel: Documenta uma classe usada como corpo de requisição ou resposta.
• @ApiModelProperty: Explica o significado e uso de um campo dentro de um modelo.