Configurando Geração de Documentação Automática com Spring Boot, OpenAPI e SpringDoc
Introdução
Documentação é um elemento crítico no desenvolvimento de APIs. Ela auxilia desenvolvedores e consumidores da API a entenderem como utilizar os recursos disponíveis. Este artigo abordará como configurar documentação automática em uma aplicação Spring Boot com OpenAPI utilizando o SpringDoc, com foco especial em configurações de segurança, autenticação e customizações.
Requisitos
- JDK 8 ou superior
- Maven ou Gradle
- Spring Boot 2.x
Adicionando Dependências
Inclua a seguinte dependência no arquivo pom.xml:
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.2.0</version>
</dependency>
Configuração Básica
Com apenas essa dependência, a documentação OpenAPI já estará acessível em http://localhost:8080/swagger-ui.html.
Configurações Avançadas
Segurança e Autenticação
Para configurar informações de segurança e autenticação, você pode ajustar sua classe de configuração OpenAPIDocumentationConfig:
@Configuration
public class OpenAPIDocumentationConfig {
@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.info(new Info()
.title("Exemplo de API")
.version("1.0"))
.components(new Components()
.addSecuritySchemes("basicScheme",
new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("basic"))
);
}
}
Anotações para Endpoints e DTOs
Anotações podem ser usadas para enriquecer a documentação gerada. Por exemplo:
@RestController
public class UserController {
@Operation(summary = "Obter todos os usuários")
@GetMapping("/users")
public List<User> getUsers() {
// código
}
@Operation(summary = "Obter usuário por ID")
@GetMapping("/users/{id}")
public User getUserById(@PathVariable Long id) {
// código
}
}
Para DTOs:
public class User {
@Schema(description = "ID do Usuário", example = "1", required = true)
private Long id;
@Schema(description = "Nome do Usuário", example = "John Doe")
private String name;
// Getters e Setters
}
Liberar Rotas na Web
Para liberar o acesso ao Swagger UI, você pode adicionar configurações no WebSecurityConfigurerAdapter:
@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {
@Override
protected void configure(HttpSecurity http) throws Exception {
http.authorizeRequests()
.antMatchers("/swagger-ui.html", "/swagger-ui/**", "/v3/api-docs/**")
.permitAll()
.anyRequest()
.authenticated()
.and()
.httpBasic();
}
}
Conclusão
Com essas configurações avançadas, você não apenas gera documentação automática para sua API, mas também incorpora informações cruciais relacionadas à segurança e autenticação, enriquece a documentação através de anotações e garante que o Swagger UI seja acessível conforme as necessidades do projeto. Isso resulta em uma API mais robusta e bem documentada, facilitando o desenvolvimento e consumo.
