Implementação da documentação do Swagger para o endpoint de Agencias (V1)

[pabloxavier]

Foram adicionadas algumas novas dependências ao projeto, no arquivo build.gradle.

    compile("io.springfox:springfox-swagger2:2.9.2")
    compile("io.springfox:springfox-swagger-ui:2.9.2")
    compile("io.springfox:springfox-bean-validators:2.9.2")

Para disponibilizar a documentação do Swagger, foi necessário adicionar um arquivo de @Configuration, similar à outros adicionados.

@Configuration
@EnableSwagger2
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfiguration {

    @Bean
    public Docket apiDoc() {

        List<ResponseMessage> defaultResponseMessages =
            ...

        return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.any())
            .paths(Predicates.not(PathSelectors.regex("/error")))
            .build()
            .apiInfo(metaData())
            .globalResponseMessage(RequestMethod.GET, defaultResponseMessages)
            .globalResponseMessage(RequestMethod.POST, defaultResponseMessages)
            .globalResponseMessage(RequestMethod.PUT, defaultResponseMessages)
            .globalResponseMessage(RequestMethod.DELETE, defaultResponseMessages);
    }

Nesta classe há outras implementações, mas a mais importante é a destacada acima.

É através deste método de @Bean, que é possível configurar vários elementos em nosso portal do Swagger, como quais os Paths que serão documentados, quais informações da API serão publicadas como nome, descrição e autor, quais os métodos e seus response codes padrões, e por aí vai.

Feita esta implementação, você terá acesso a dois nos Links em seu "servidor" (considerando que você esteja com a API exposta na porta 8088): http://localhost:8088/v2/api-docs http://localhost:8088/swagger-ui.html

No demais, são caracterizações que você fará dos seus Endpoints, seus Comandos de entrada, e suas Representações de saída.

Seguem alguns exemplos.

Anotando informações do Endpoint:

    @ApiOperation(
            value = "Incluir uma nova agência.",
            response = AgenciaInclusaoCommand.class)
    @ApiResponses(value = {
            @ApiResponse(code = 201, message = "Agência criada com sucesso."),
            @ApiResponse(code = 400, message = "Inclusão não permitida por validações.")
    })
    @PostMapping
    public ResponseEntity<?> incluirAgencia(
            @RequestBody AgenciaInclusaoCommand comando){

        Agencia agenciaIncluida = service.salvar(comando);
        AgenciaRepresentationV1 model = AgenciaRepresentationV1.from(agenciaIncluida);
        return created(model, agenciaIncluida.getCodigo());
    }

Anotando informações do Command:

public class AgenciaInclusaoCommand {

    @NotNull
    @Range(min = 1, max = 9999)
    @FieldName("Número")
    @ApiModelProperty(notes = "Número de identificação da agência.")
    private Integer numero;

    @NotNull(message = "{agencia.nome.nao.nulo}")
    @NotBlank(message = "{agencia.nome.nao.vazio}")
    @ApiModelProperty(notes = "Nome da agência.")
    private String nome;

    ...

Anotando informações da Representation:

@ApiModel(description = "Classe de modelo (representação de agência).")
public class AgenciaRepresentationV1 {

    @ApiModelProperty(notes = "Código da agência (autonumerável).")
    private Integer codigo;

    @ApiModelProperty(notes = "Número de identificação da agência.")
    private Integer numero;

    @ApiModelProperty(notes = "Nome fantasia.")
    private String nome;

    @ApiModelProperty(notes = "CNPJ da agência.")
    private String cnpj;   

    ...