Questão nº 26
Questão de Tecnologia da Informação · FCC TRF4 2025 (nº 26)
Uma analista está trabalhando em uma API Spring Boot e precisa documentar os endpoints utilizando anotações do Swagger para descrever operações, parâmetros e respostas. Ela quer garantir que a documentação seja clara e compatível com a especificação OpenAPI 3.0, mas está incerta sobre qual conjunto de anotações usar e como aplicá-las corretamente em um controlador. O endpoint em questão é um `GET /processos/{id}` que retorna os detalhes de um processo. Nesse cenário, a maneira correta de anotar o endpoint `GET /processos/{id}` em um controlador Spring Boot para garantir uma documentação precisa e compatível com OpenAPI 3.0, usando a biblioteca `springdoc-openapi`, é usar
- A`@ApiOperation` e `@ApiParam` do pacote `io.swagger.annotations` para descrever a operação e o parâmetro.
- B`@ApiResponse` do pacote `io.swagger.annotations` combinado com `@Operation` do pacote `io.swagger.v3.oas.annotations`.
- Capenas `@GetMapping` sem anotações do Swagger, pois `springdoc-openapi` gera documentação automaticamente.
- D`@Schema` no método do controlador para descrever o parâmetro `{id}`.
- E`@Operation` e `@Parameter` do pacote `io.swagger.v3.oas.annotations` para descrever a operação e o parâmetro. (alternativa correta)
Resposta comentada
Gabarito Alternativa E
Para documentar uma API com OpenAPI 3.0 e springdoc-openapi no Spring Boot, usamos anotações específicas que detalham operações (endpoints) e seus componentes, como parâmetros e respostas.
- (A) Incorreta: Essas anotações (
@ApiOperation,@ApiParam) pertencem à especificação Swagger 2.0 (usada pelo Springfox), enquanto a questão pede compatibilidade com OpenAPI 3.0 espringdoc-openapi, que utiliza as anotações do pacoteio.swagger.v3.oas.annotations. - (B) Incorreta: Mistura anotações de diferentes versões (
@ApiResponsedo Swagger 2.0 e@Operationdo OpenAPI 3.0), o que não é a abordagem correta nem consistente para OpenAPI 3.0. A anotação correta para respostas em OpenAPI 3.0 é@ApiResponsedo pacoteio.swagger.v3.oas.annotations.responses. - (C) Incorreta: Embora
springdoc-openapigere documentação básica automaticamente, para garantir uma documentação clara, precisa e detalhada (como requerido pela analista para descrever operações, parâmetros e respostas), é fundamental usar anotações explícitas do OpenAPI 3.0. A geração automática não oferece o nível de detalhe necessário. - (D) Incorreta: A anotação
@Schemaé usada para descrever a estrutura de modelos de dados (DTOs, objetos), não para descrever diretamente um parâmetro de método como{id}. Para parâmetros, usa-se@Parameter. - (E) Correta:
@Operationé a anotação padrão para descrever a operação completa de um endpoint (sumário, descrição, tags), e@Parameteré a anotação correta para descrever parâmetros individuais (como o{id}do path), ambos do pacoteio.swagger.v3.oas.annotations, que é o conjunto de anotações para OpenAPI 3.0 utilizado pelospringdoc-openapi.
Fonte: FCC TRF4 2025 Técnico Judiciário - Área Apoio Especializado - Especialidade Desenvolvimento de Sistema da Informação (Caderno Tipo 001). Reproduzida para fins de estudo.