0

Documentando a API com Swagger 2 e Postman

André Gomes
André Gomes

Também pode ser visualizado pela implementação do Swagger 2


Além da documentação dos endpoints, foi implementada a documentação da camada de controle como o exemplo abaixo:

@Api("Gerencia o Usuario")
public interface UsuarioControllerDoc {


    @ApiOperation(value = "Operação de criação da Usuario.")
    @ApiResponses(value = {
            @ApiResponse(code = 201, message = "Sucesso na criação da Usuario."),
            @ApiResponse(code = 400, message = "Erro nos atributos informados ou atributos faltantes.")
    })
    ResponseEntity<UsuarioDTO> createUsuario(UsuarioDTO usuarioDTO);


    @ApiOperation(value = "Operação de alteração da Usuario.")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "Sucesso na alteração da Usuario."),
            @ApiResponse(code = 400, message = "Erro nos atributos informados ou atributos faltantes."),
            @ApiResponse(code = 404, message = "Usuario não encontrada.")
    })
    ResponseEntity<UsuarioDTO> updateUsuario(UsuarioDTO usuarioDTO);


    @ApiOperation(value = "Operação de exclusão da Usuario.")
    @ApiResponses(value = {
            @ApiResponse(code = 204, message = "Sucesso na exclusão da Usuario."),
            @ApiResponse(code = 404, message = "TUsuario não encontrada.")
    })
    ResponseEntity<UsuarioDTO> deleteUsuario(Long id) throws Exception;


    @ApiOperation(value = "Operação de busca por um Usuario específico.")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "Sucesso no retorno da Usuario."),
            @ApiResponse(code = 404, message = "Usuario não encontrada.")
    })
    ResponseEntity<UsuarioDTO> findUsuarioById(Long id) throws Exception;


    @ApiOperation(value = "Operação de busca por todos os Usuario.")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "Sucesso no retorno da Usuario."),
            @ApiResponse(code = 404, message = "Usuario não encontrada.")
    })
    ResponseEntity<List<UsuarioDTO>> listAllUsuario();
}

Contrato implementado na classe UsuarioController:

@RestController
@RequestMapping("/usuario")
public class UsuarioController implements UsuarioControllerDoc {

    private final UsuarioService service;

    @Autowired
    public UsuarioController(UsuarioService service) {
        this.service = service;
    }

    @Override
    @PostMapping
    public ResponseEntity<UsuarioDTO> createUsuario(@Valid @RequestBody UsuarioDTO usuarioDTO) {
        return ResponseEntity.status(HttpStatus.CREATED)
                .body(service.save(usuarioDTO));
    }
...


Documentação publicada pelo Postman Documenter.getPostman:


A publicação do Postman facilita o compartilhamento para testes por outros membros da equipe pois inclui o formato dos requests e os objetos já testados, além de opções de liguagens de programação.


Conclusão, o Postman é realmente mão na roda para executar testes de endpoints, rápido, prático e funcional.

0
0

Comentários (0)

Tecnólogo: Gestão de TI | MBA: Ciência de Dados e Inteligência Artificial

Brasil