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

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>

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", "", "support@example.com"))
                        .build());
    }
}

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
}

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

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.

Documentando uma API com Java Spring Boot usando Swagger