Documentando uma API com Java Spring Boot usando Swagger

Passos para documentar uma RESTful API em Java Spring Boot com Swagger

1. Adicionar dependências do Swagger

Adicione as dependências do Swagger no arquivo pom.xml:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

1. Configurar o Swagger

Crie uma classe de configuração do Swagger:

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(new ApiInfoBuilder()
                        .title("My API")
                        .description("This is a RESTful API in Java Spring Boot using Swagger")
                        .version("1.0")
                        .contact(new springfox.documentation.service.Contact("API Support", "", "[e-mail]"))
                        .build());
    }
}

1. Adicionar Anotações Swagger para Descrever Endpoints, Parâmetros e Respostas

Anotações de Operação:

Para cada endpoint, adicione anotações com detalhes da requisição HTTP, caminho e um resumo básico.

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@RestController
@RequestMapping("/movies")
@Api(tags = "Movies")
public class MovieController {

    @ApiOperation(value = "Get a list of movies", notes = "Retrieves a list of movies")
    @GetMapping
    public List<Movie> getMovies() {
        // code ...
    }

    @ApiOperation(value = "Get a movie by ID", notes = "Retrieves a movie by its ID")
    @GetMapping("/{id}")
    public Movie getMovie(
            @ApiParam(value = "ID of the movie to be obtained", required = true) 
            @PathVariable String id) {
        // code ...
    }
}

Definindo Modelos de Resposta:

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(description = "Details about the Movie")
public class Movie {

    @ApiModelProperty(notes = "The unique ID of the movie")
    private String id;

    @ApiModelProperty(notes = "The name of the movie")
    private String name;

    // getters and setters
}

@ApiModel(description = "Details about the ErrorResponse")
public class ErrorResponse {

    @ApiModelProperty(notes = "The error code")
    private int code;

    @ApiModelProperty(notes = "The error message")
    private String message;

    // getters and setters
}

1. Gerar a Documentação do Swagger

Inicie a aplicação Spring Boot e acesse a interface Swagger UI no navegador:

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

1. Boas Práticas de Documentação

• Use linguagem descritiva e sucinta para ajudar no entendimento da API.
• Organize a ordem das anotações de forma lógica para seguir um fluxo claro e padronizado, facilitando a manutenção.
• Atualize a documentação sempre que houverem mudanças na API para mantê-la consistente e útil.

Seguindo esses passos, você poderá documentar sua API em Java Spring Boot usando Swagger de maneira eficaz e clara.