Executando verificação de segurança...
1

Discussão sobre documentação de API com Swagger

Estou em busca do meu primeiro emprego como Programador Java, e pra compor meu portfolio fiz uma aplicação com frontend de React e backend com MongoDB,SpringBoot e, obviamente, Java e eu quero documentar a aplicação, não porque seja realmente necessário documentar minha aplicação, já que ela é relativamente pequena, mas pra mostrar que tenho essa skill, enfim, eu pesquisei tutoriais e cheguei a um tutorial que se utilizava do swagger e a documentação aparecia com a url do localhost, eu implementei a dependência no meu pom.xml, documentei a classe que roda a API, até ai, excelente, só que eu me deparei com um problema, acho que o código fica extremamente feio, não modularizado e "amador" quando eu documento direto no arquivo, ai eu busquei implementar em um novo package e numa nova classe, só que eu não estou conseguindo entender muito bem como associar o endpoint que eu quero documentar com a classe nesse novo package queria entender como faço isso. segue o exemplo de como estou fazendo:

package dev.SuperDeMou.movies.swaggerConfig;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.OpenAPI;

@Configuration
public class OpenApiConfig_Main {

    @Bean
    OpenAPI customOpenAPI() {
        return new OpenAPI()
            .info(new Info()
                .title("Movie API")
                .version("1.0.0")
                .description(
                    "Essa API realiza a tarefa de conectar o banco de dados MongoDB Atlas a um site feito em React. " +
					  "A aplicação é responsável por receber os dados do banco de dados e enviá-los para o frontend, permitindo que sejam recebidos:\n" +
					  "\n" +
					  "**_id**: Responsável por identificar de qual filme o JSON deverá ser inserido.\n" + 
					  "\n" +
					  "**imdbId**: É o ID que fica exposto para o usuário e tem a função de acessar o filme representado por esse imdbId.\n" + 
					  "\n" +
					  "**title**: Título do filme.\n" + 
					  "\n" +
					  "**releaseDate**: Data de lançamento.\n" + 
					  "\n" +
					  "**trailerLink**: Link do trailer hospedado no YouTube.\n" + 
					  "\n" +
					  "**genres**: Os gêneros aos quais esse filme pertence, como Ação, Romance, etc.\n" +
					  "\n" + 
					  "**poster**: O pôster do filme.\n" + 
					  "\n" +
					  "**backdrops**: Imagens de diferentes tamanhos para diferentes tipos de tela.\n" + 
					  "\n" +
					  "**reviewIds**: Os IDs de cada análise.\n" + 
					  "\n" +
					  "**reviews**: As análises dos usuários."
                )
                .contact(new io.swagger.v3.oas.models.info.Contact()
                    .name("Gustavo")
                    .email("[email protected]")
                )
            );
    }
}
Dependência utilizada no Maven:
<dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.2.0</version>
        </dependency>
    </dependencies>

e simplesmente não estou vendo como vou referenciar a classe principal, quando eu rodo a aplicação "funciona", mas na minha visão não é porque está funcionando que está certo, e eu tenho a sensação de que, quando eu implementar isso em outros endpoints isso pode dar errado ou simplesmente não aparecer como deveria, ou se documentar com swagger é uma boa prática, enfim, gostaria de esclarecer se é uma boa prática documentar os endpoints, se eu tenho que colocar apenas o titulo e descrição ou eu preciso declarar outras coisas nos endpoints, ou quaisquer outro feedback, que será muito bem vindo.

Carregando publicação patrocinada...
1

Opa, e ai meu nobre.

Acredito que para deixar melhor organizado no atributo description onde você tentou documentar a API por inteiro, você deve apenas dar uma breve descrição do intuito da sua API.

Para detalhar melhor cada endpoint da sua API sugiro que você utilize as anotações de documentação do próprio swagger dentro dos controllers e em cada metodo de acordo com esse link.

Por fim, se você quiser deixar bem mais organizado pode criar interfaces e colocar as anotações do swagger citadas anteriormente nelas e apenas implementa-las nas classes de cada controller que você tiver.

1