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.