DEV Community: Paulo Neto

Documentando API's com Springdoc OpenAPI

Paulo Neto — Wed, 05 Mar 2025 17:50:20 +0000

No mundo do desenvolvimento de software, especialmente no contexto de APIs REST, uma documentação clara e precisa é essencial para garantir a compreensão e a usabilidade das interfaces. No ecossistema Java, a combinação de Spring Docs e Bean Validation oferece uma abordagem robusta e eficaz para construir APIs bem documentadas e com validações automáticas. Neste artigo, vamos explorar as vantagens dessa implementação e como ela pode melhorar a qualidade do seu projeto.

Documentação de APIs REST com Spring Docs

A documentação de uma API é crucial para a interação com outros sistemas e desenvolvedores. Sem uma documentação adequada, pode-se gerar confusão, erros e falta de compreensão sobre o funcionamento da API. O Spring Docs facilita esse processo, especialmente quando se utiliza o Spring Boot para construir suas APIs REST.

O Spring Docs é frequentemente integrado com o Swagger, uma ferramenta amplamente utilizada para gerar documentação interativa de APIs. A vantagem principal de usar o Spring Docs é a facilidade de configuração e a capacidade de gerar documentação automaticamente a partir do código. Utilizando anotações como @Api, @ApiOperation, @ApiResponse, entre outras, é possível fornecer uma descrição detalhada das rotas, parâmetros, tipos de resposta e erros que a API pode gerar.

Por exemplo, ao anotar um endpoint da seguinte maneira:

@Tag(name = "categorias", description = "API para ações no recurso Categoria")
@RestController
@RequestMapping("categorias")
public class CategoriaController {

    private final CategoriaService service;

    public CategoriaController(final CategoriaService c) {
        this.service = c;
    }

    @Operation(summary = "Cria uma nova Categoria", description = "Cria uma nova Categoria, caso ela não exista", tags = "categorias")
    @ApiResponses(value = { 
            @ApiResponse(
                    description = "Ação realizada com sucesso", responseCode = "201",
                    content = { @Content(mediaType = "application/json", 
                    schema = @Schema(implementation = CategoriaDTO.class)) }),
            @ApiResponse(
                    description = "Categoria exitente", responseCode = "409",
                    content = { @Content(mediaType = "application/json", 
                    schema = @Schema(implementation = Erro.class)) }),
            @ApiResponse(
                    description = "Ocorreu um erro interno inesperado na API", responseCode = "500",
                    content = { @Content(mediaType = "application/json", 
                    schema = @Schema(implementation = Erro.class)) }) 
            }
    )
    @PostMapping(value = "/", produces = MediaType.APPLICATION_JSON_VALUE)
    @ResponseStatus(HttpStatus.CREATED)
    public CategoriaDTO create(
            @Valid @RequestBody @NotBlank(message = "O nome da nova Categoria não pode ser vazio!") String novaCategoria) {
        var dto = service.create(novaCategoria);
        return dto;
    }
}

O Spring Docs, juntamente com o Swagger, gera automaticamente a documentação interativa da API, permitindo que os desenvolvedores testem a API diretamente pela interface. Isso aumenta a produtividade da equipe e reduz a margem de erro, já que a documentação está sempre em sincronia com o código.
Para acessar a documentação gerada, acesse: http://localhost:8080/swagger-ui/index.html

Validação de Campos com Bean Validation

A validação de dados de entrada é outra prática essencial em APIs RESTful. No Spring, o Bean Validation é uma das ferramentas mais poderosas para garantir que os dados recebidos nos endpoints atendam aos critérios definidos. Isso não só melhora a confiabilidade da aplicação, como também evita a necessidade de escrever validações manuais e repetitivas.

O Bean Validation utiliza anotações como @NotNull, @Size, @Email, @min, entre outras, que podem ser aplicadas diretamente nas entidades ou nos parâmetros dos métodos. A validação é feita automaticamente pelo Spring antes de os dados serem processados, e caso algum dado inválido seja enviado, o Spring lança uma exceção de erro com uma mensagem clara sobre o que está errado.

Exemplo de validação utilizando Bean Validation:

@Getter
@Setter
public class ProdutoRequest implements Serializable {

    private static final long serialVersionUID = 1L;

    @NotBlank(message = "O nome do produto é obrigatório!")
    private String nome;

    @NotBlank(message = "Uma descrição para o produto é obrigatório!")
    private String descricao;

    @Positive(message = "Um preço para o produto é obrigatório!")
    private BigDecimal preco;

    @NotNull(message = "Um ID de uma categoria deve se informado!")
    private Long categoriaId;

}

Ao utilizar essas anotações, o Spring Boot automaticamente valida os dados e, se houver algum erro, retorna uma resposta 400 (Bad Request) com uma mensagem detalhada sobre qual campo falhou na validação. Isso reduz a carga de trabalho do desenvolvedor e evita que erros de dados inválidos cheguem à camada de serviço ou banco de dados.

Vantagens da Implementação

Melhoria na Manutenção e Produtividade: A documentação automática reduz o tempo gasto criando e mantendo documentações desatualizadas, pois ela é gerada diretamente a partir do código-fonte. As anotações utilizadas no Spring Docs ficam sempre sincronizadas com os endpoints, facilitando futuras modificações e atualizações na API.
Consistência e Confiabilidade: A validação automática com Bean Validation garante que todos os dados recebidos sejam consistentes e atendam aos requisitos de integridade definidos. Isso minimiza erros humanos e aumenta a confiabilidade da API.
Facilidade de Uso para Consumidores da API: A documentação interativa do Swagger proporciona um ambiente onde outros desenvolvedores ou sistemas podem testar a API diretamente, sem necessidade de configurar um cliente separado. Isso acelera a integração e melhora a experiência do consumidor da API.
Escalabilidade: Ao combinar validação automática com uma documentação gerada de forma inteligente, o desenvolvedor pode escalar a API de forma mais segura e eficiente, pois as mudanças na API refletem diretamente na documentação e nas validações sem exigir trabalho adicional manual.
Redução de Erros e Melhor Debugging: Quando a validação de dados falha, a API retorna respostas claras e úteis, facilitando a identificação e correção de erros. Isso acelera o ciclo de desenvolvimento e torna mais fácil para os desenvolvedores depurarem a aplicação.

Conclusão

Integrar Spring Docs com Bean Validation em uma API REST é uma prática altamente recomendada para garantir que as APIs sejam bem documentadas e, ao mesmo tempo, seguras. A documentação automática melhora a interação entre desenvolvedores e sistemas, enquanto a validação de campos oferece maior confiança na integridade dos dados. Essa combinação de ferramentas do Spring resulta em uma arquitetura de API mais robusta, escalável e de fácil manutenção. Ao adotar essas práticas, você garante que sua API seja não só eficiente, mas também de fácil uso e integração para outros desenvolvedores.

Referências

Documentação do Springdocs
Documentação do Bean Validation
Fontes com o exemplo de implementação

Protegendo suas API's com Keycloak

Paulo Neto — Mon, 03 Mar 2025 17:05:47 +0000

Dando continuidade ao post que fiz há um tempo sobre representação de arquitetura de aplicações com diagramas C4, neste post trago uma questão muito importante quando falamos sobre desenvolvimento de API's Rest, que é a segurança. Para exemplificar a segurança em API's Rest, trago um exemplo de implementação de um dos componentes da arquitetura representada no diagrama do post anterior. Neste post apresento a implementação do microservice ecommerce-ms-product implementado com Java 17, JPA e Spring Boot. Para a segurança da API utilizei o Keycloak como Identity and Access Management(IAM).

O que é um Identity and Access Management(IAM)?

A gestão de identidade e acesso oferece supervisão sobre a autenticação de usuários e a disponibilidade de recursos. Frequentemente referida como IAM, essa tecnologia assegura que as pessoas adequadas tenham acesso aos recursos digitais apropriados no momento oportuno e pelas razões corretas.

Conceitos básicos sobre IAM

Um recurso digital refere-se a qualquer combinação de aplicativos e dados dentro de um sistema computacional. Entre os exemplos, estão aplicativos web, APIs, plataformas, dispositivos e bancos de dados.

No centro do IAM está a identidade. Alguém deseja acessar seu recurso, seja um cliente, funcionário, membro ou participante. No contexto do IAM, uma conta de usuário corresponde a uma identidade digital. Além de representar pessoas, essas contas também podem estar associadas a elementos não humanos, como softwares, dispositivos da Internet das Coisas (IoT) ou robôs.

A autenticação consiste na verificação de uma identidade digital, garantindo que alguém (ou algo) comprove ser quem afirma.
Já a autorização determina quais recursos um usuário tem permissão para acessar.

Os padrões de autenticação e autorização são essenciais para garantir a segurança e a eficiência dos sistemas de gerenciamento de identidade (IAM). Os mais reconhecidos e amplamente adotados na indústria incluem:

OAuth 2.0: Protocolo de autorização que permite acesso seguro a recursos sem expor credenciais.
OpenID Connect (OIDC): Extensão do OAuth 2.0 para autenticação, permitindo que usuários se identifiquem de maneira segura.
SAML (Security Assertion Markup Language): Protocolo baseado em XML usado para autenticação e troca de informações de identidade entre diferentes sistemas.
FIDO2/WebAuthn: Padrão para autenticação sem senha, baseado em chaves criptográficas.
LDAP (Lightweight Directory Access Protocol): Protocolo usado para acessar e manter diretórios de informações sobre usuários e dispositivos.

Esses padrões são amplamente considerados os mais seguros e confiáveis para gerenciar identidades, proteger dados pessoais e controlar o acesso a recursos.

Client Credentials Flow

Na implementação utilizei o Client Credentials Flow(definido no OAuth 2.0 RFC 6749, seção 4.4) envolve um aplicativo trocando suas credenciais de aplicativo, como client ID e client secret, por um token de acesso.

Este fluxo é mais adequado para aplicativos Máquina-a-Máquina (M2M), como CLIs, daemons ou serviços de backend, porque o sistema deve autenticar e autorizar o aplicativo em vez de um usuário.

Na prática

Na implementação do microservice ecommerce-ms-product criei duas coleções de recurso:

/produtos /categorias

Nelas implementei endpoints para criar, consultar deletar e atualizar esses recursos. Para proteger esses endpoints, para que sejam acessados apenas por quem tem as credenciais necessárias, adicionei no aquivo application.properties do projeto a seguinte entrada:

spring.security.oauth2.resourceserver.jwt.issuer-uri=http://localhost:7080/realms/security-ecommerce-api

Essa entrada configura a aplicação para utilizar o realm security-ecommerce-api que foi criado no Keycloak

Também adicionei as seguintes dependências do Spring no projeto:

        <dependency>
            <groupId>org.springframework.security</groupId>
            <artifactId>spring-security-config</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
        </dependency>

Com essas dependências no projeto, os endpoints do projeto já ficam indisponíveis, sendo acessadas apenas por quem tem as credenciais adequadas.

Configuração do Realm security-ecommerce-api

Na área interna do Keycloak, crie um novo Realm:

No Realm criado, vá ao menu Clients e crie um novo Client:

No nosso exemplo, criei o client ID ecommerce-client, o client secret é gerado pelo Keycloak e apresentado na aba Credentials:

Testando a API segura

Para testar essa implementação, utilizei uma extensão do VSCode, Rest Client para executar requisições:

Configuração para Keycloak local

Para rodar o Keycloak local utilizei o Docker e Compose para subir os serviços do Mysql, para a base de dados do Keycloak, e do Keycloak.

services:

  mysqlsrv:
    image: mysql:5.7
    environment:
        MYSQL_ROOT_PASSWORD: "MySql2019!"
        MYSQL_DATABASE: "ecommerce-produtos"
    ports:
      - "3306:3306"
    volumes:
      - /home/paulo/Desenvolvimento/docker/mysql:/var/lib/mysql
    networks:
      - ecommerce-network

  keycloak:
    image: quay.io/keycloak/keycloak:24.0
    container_name: keycloak-ecommerce
    environment:
      KC_HOSTNAME: localhost
      KC_HOSTNAME_PORT: 7080
      KC_HOSTNAME_STRICT_BACKCHANNEL: "true"
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin
      KC_HEALTH_ENABLED: "true"
      KC_LOG_LEVEL: info
      KC_DB: mysql
      KC_DB_USERNAME: root
      KC_DB_PASSWORD: MySql2019!
      KC_DB_URL_HOST: mysqlsrv
      KC_DB_URL_PORT: 3306
      KC_DB_SCHEMA: keycloak
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:7080/health/ready"]
      interval: 15s
      timeout: 2s
      retries: 15
    command: ["start-dev", "--http-port", "7080", "--https-port", "7443"]
    ports:
      - "7080:7080"
      - "7443:7443"
    networks:
      - ecommerce-network
    depends_on: 
      - mysqlsrv

networks: 
  ecommerce-network:
    driver: bridge

Por que representar a arquitetura de uma aplicação em diagramas?

Paulo Neto — Thu, 16 Nov 2023 00:33:58 +0000

Você já pediu a um desenvolvedor para ele explicar como funciona o software que ele desenvolveu/desenvolve? Provavelmente a resposta vai conter algum rabisco de caixinhas e setas, na tentativa de representar visualmente como os componentes do software em questão se comunicam.

Na industria de software existem algumas notações conhecidas para representar a arquitetura de um software, como Linguagem de Modelagem Unificada (UML), o ArchiMate e o SysML. Porém na tentativa de "agilizar" a entrega, muitas equipes descartam essas notações e utilizam "caixinhas e setas" mais simples, na tentativa de representar a arquitetura do software. Mas será que vale descartar essas notações? Será que as equipes de desenvolvimento ainda conseguem representar bem a arquitetua?

Diagramas C4

O modelo C4 foi criado como uma forma de ajudar as equipes de desenvolvimento de software a descrever e comunicar a arquitetura de software, tanto durante sessões iniciais de design quanto ao documentar retrospectivamente uma base de código existente. Com ele podemos representar em diversos níveis de detalhe como uma aplicação funciona.
O modelo C4 sugere 4 níveis visões de diagramas para a representação de um software:

Nível 1, System Context: Visão de como o a aplicação se comunica com mundo ao seu redor.
Nível 2, Container: Amplia o escopo da aplicação, mostrando os blocos de construção técnicos de alto nível.
Nível 3, Component: Amplia um contêiner individual, mostrando os componentes dentro dele.
Nível 4, Code: Um diagrama de código, class UML por exemplo, pode ser usado para ampliar um componente individual, mostrando como esse componente é implementado.

Nesse Post apresento um exemplo do diagrama Nível 3 Component e como escrever utilizando o PlantUml, em outras postagens trarei exemplos dos demais níveis.

Contexto da Aplicação

A aplicação em questão é um E-commerce fictício, e o diagrama de Componentes apresenta a responsabilidade de cada um dos componentes da aplicação e suas integrações.

C-4 PlantUML

Para criar esse diagrama utilizei o C-4 PlantUml que fornece uma forma simples de criar diagras utilizando a sintaxe do PlantUml, segue o código desse diagrama

@startuml
title <size:45>C4 Component diagram to Generic E-Commerce
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml
!define DEVICONS https://raw.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/master/devicons
!define DEVICONS2 https://raw.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/master/devicons2
!define SPRITESURL https://raw.githubusercontent.com/rabelenda/cicon-plantuml-sprites/v1.0/sprites
!define FONTAWESOME https://raw.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/master/font-awesome-5
!includeurl SPRITESURL/kafka.puml
!includeurl SPRITESURL/cassandra.puml
!includeurl SPRITESURL/redis.puml
!include DEVICONS2/nestjs.puml
!include DEVICONS/angular.puml
!include DEVICONS/java.puml
!include DEVICONS/nodejs.puml
!include DEVICONS/mysql.puml
!include DEVICONS/redis.puml

!include FONTAWESOME/users.puml



Person(customer, "E-commerce customer", "Customer who wants to buy a product or service")


System_Boundary(core, "E-commerce Component core "){
    Container(product,"API ecommerce-ms-product", "Java - Quarkus", $sprite="java")
    Container(order,"API ecommerce-ms-order", "Java - Quarkus", $sprite="java")
    ContainerDb(product_db,"Database","MySql", "Holds product information", $sprite="cassandra")
    ContainerDb(order_db,"Database","Cassandra", "Holds order and invoice information", $sprite="mysql")
    ContainerDb(redisDB,"Memory Database","Redis","Memory database for search itens, cart itens, order and invoice information", $sprite="redis")
    Container(email, "API ecommerce-ms-email", "Java - Quarkus", "Service for email send", $sprite="java")

    System_Boundary(sale, "Sale components"){
        ContainerQueue(orderTopic,"TOPIC", "Kafka", "Topic for new order event", $sprite="kafka")
        Container(orderConsumer, "Consumer", "Nestjs", "Consumer of new order event", $sprite="nestjs")
        ContainerQueue(nfseTopic,"TOPIC", "Kafka", "Topic for issuing invoices event", $sprite="kafka")
        Container(nfseConsumer, "Consumer", "Nestjs", "Consumer of invoice issuance events", $sprite="nestjs")
    }
}

System_Boundary(app, "E-commerce Aplication "){
    Container(spa, "SPA", "Angular", "The main interface that the customer interacts with", $sprite="angular")
    Container(bff,"BFF","NodeJs","Backend to interface SPA", $sprite="nodejs")

}

System_Boundary(external, "External components"){
    Component_Ext(payment,"API", "Payment service")
    Component_Ext(nfse,"API", "NFS-e service")
}

Rel_Neighbor(customer,spa,"Uses","https")

Rel_R(spa,bff,"Use","https")
Rel(product,product_db, "Read/Write", "tcp")
Rel(order,order_db, "Read/Write", "tcp")

Rel_D(bff,product,"List products","https")
Rel(bff, orderTopic, "New order event", "tcp")
Rel(bff,redisDB, "Save cart itens, search", "http")
Rel_R(orderTopic, orderConsumer,"Order process","tcp")
Rel(orderConsumer,payment, "Confirm payment?", "https")
Rel(orderConsumer,order, "Save new order", "https")
Rel(orderConsumer,product,"Decreases inventory of sale products", "https")
Rel(orderConsumer,nfseTopic, "Confirmed payment, issue invoice event", "tcp")
Rel(nfseTopic,nfseConsumer, "Consumes","tcp")
Rel(nfseConsumer, nfse, "Uses", "https")
Rel(orderConsumer,email, "Send purchase confirmation email", "https")

@enduml

Uma representação bem feita dos componentes de uma aplicação e suas integrações pode te polpar algumas horas de reuniões na sua semana.

Para saber mais sobre o C-4 Model
Sobre a sintaxe do C-4 PlantUML

Plugin do VSCode para o PlantUML