DEV Community: Fabiano Góes • e-Programar

Documentando uma API REST Spring Boot 3 usando OpenAPI 3.0

Fabiano Góes • e-Programar — Tue, 09 Jan 2024 00:00:45 +0000

Visão Geral

A documentação é uma parte essencial da construção de APIs REST. Neste tutorial, veremos SpringDoc, que simplifica a geração e manutenção de documentos de API com base na especificação OpenAPI 3 para aplicativos Spring Boot 3.x.

Configuração

Spring Boot 3.x requer o uso da versão 2 do springdoc-openapi:



ext {
    springdocVersion = "2.3.0"
}

dependencies {
    implementation "org.springframework.boot:spring-boot-starter-web"
    // ...
    implementation "org.springframework.boot:spring-boot-starter-validation"
    implementation "org.springdoc:springdoc-openapi-starter-webmvc-ui:${springdocVersion}"
    implementation "org.springdoc:springdoc-openapi-starter-common:${springdocVersion}"
    // ...
    testImplementation "org.springframework.boot:spring-boot-starter-test"
}

Depois de configurar a dependência corretamente, podemos executar nossa aplicação e encontrar as descrições da OpenAPI em /v3/api-docs, que é o caminho padrão:



http://localhost:8080/v3/api-docs

Podemos personalizar o caminho em application.properties usando a propriedade springdoc.api-docs. Por exemplo, podemos definir o caminho para /api-docs:



springdoc.api-docs.path=/api-docs

Então, poderemos acessar a documentação na url:



http://localhost:8080/api-docs

As definições OpenAPI estão no formato JSON por padrão. Para o obter o formato yaml, podemos podemos acessar a url:



http://localhost:8080/api-docs.yaml

Integração com UI Swagger

Além de gerar a especificação OpenAPI 3, podemos integrar springdoc-openapi com Swagger UI para interagir com nossa especificação de API e testar os endpoints. A dependência springdoc-openapi já inclui a UI do Swagger, então neste ponto, já podemos acessar a Swagger UI em:



http://localhost:8080/swagger-ui/index.html

Support for swagger-ui Properties

A biblioteca springdoc-openapi também suporta propriedades swagger-ui. Elas podem ser usados como propriedades Spring Boot com o prefixo springdoc.swagger-ui. Por exemplo, podemos personalizar o caminho da Swagger UI alterando a propriedade springdoc.swagger-ui.path dentro do nosso arquivo application.properties:



springdoc.swagger-ui.path=/documentation.html

Então podemos acessar a Swagger UI na url:



http://localhost:8080/documentation.html

API de exemplo



import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.util.UriComponentsBuilder;

import java.util.Collection;

@RestController
@RequestMapping("/api/books")
public class BookController {

    private final BookRepository repository;

    public BookController(BookRepository repository) {
        this.repository = repository;
    }

    @PostMapping
    public ResponseEntity<?> create(@RequestBody final Book payload, UriComponentsBuilder ucb) {
        Book book = repository.create(payload);

        var location = ucb
                .path("/movies/{id}")
                .buildAndExpand(book.getId())
                .toUri();

        return ResponseEntity.created(location).build();
    }

    @GetMapping("/{id}")
    public Book findById(@PathVariable final Long id) {
        return repository.findById(id)
            .orElseThrow(BookNotFoundException::new);
    }

    @GetMapping("/")
    public Collection<Book> findBooks() {
        return repository.getBooks();
    }

    @PutMapping("/{id}")
    @ResponseStatus(HttpStatus.OK)
    public ResponseEntity<?> update(@PathVariable("id") final Long id, @RequestBody final Book payload) {
        if (repository.findById(id).isEmpty()) return ResponseEntity.notFound().build();

        return ResponseEntity.accepted().body(repository.update(id, payload));
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<?> delete(@PathVariable final Long id) {
        Book book = repository.findById(id).orElseThrow(BookNotFoundException::new);
        repository.delete(book);
        return ResponseEntity.noContent().build();
    }
}

Repositório de exemplo



import org.springframework.stereotype.Repository;
import java.util.*;

@Repository
public class BookRepository {

    private final Map<Long, Book> books = new HashMap<>();

    public Optional<Book> findById(final long id) {
        return Optional.ofNullable(books.get(id));
    }

    public Book create(Book book) {
        Long id = (long) (books.size() + 1);
        book.setId(id);
        books.put(id, book);
        return books.get(id);
    }

    public Collection<Book> getBooks() {
        return books.values();
    }

    public Book update(final long id, final Book book) {
        Book bookUpdate = books.get(id);
        bookUpdate.setAuthor(book.getAuthor());
        bookUpdate.setTitle(book.getTitle());
        books.put(id, bookUpdate);

        return books.get(id);
    }

    public void delete(final Book book) {
        books.remove(book.getId());
    }
}

Modelo de exemplo



import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;

public class Book {
    private long id;
    private String title;
    private String author;

    // Getters and Setters
}

class BookNotFoundException extends RuntimeException {
}

Application Properties de exemplo




# Open Api
springdoc.api-docs.path=/api-docs
springdoc.swagger-ui.operationsSorter=alpha
springdoc.api-docs.version=OPENAPI_3_0
spring.jpa.hibernate.ddl-auto=none

# Swagger
springdoc.swagger-ui.path=/documentation.html

Testando

Então, se executarmos nossa API agora, podemos visualizar a documentação em:



http://localhost:8080/documentation.html

Aqui podemos usar a Swagger UI para testar nossa API fazendo:

cadastro de novos livros
obtendo todos os livros cadastrados
obtendo um livro pelo id
atualizando um livro cadastrado
deletando um livro cadastrado

Faça testes e explore a Documentação gerada automáticamente.

Geração automática de documentos usando validação de bean JSR-303

Quando nosso modelo inclui anotações de validação de bean JSR-303, como @NotNull, @NotBlank, @Size, @Min e @Max, a biblioteca springdoc-openapi utiliza essas anotações para gerar documentação de esquema adicional para as restrições correspondentes. Vejamos um exemplo usando nosso bean Book:



public class Book {

    private long id;

    @NotBlank
    @Size(min = 0, max = 20)
    private String title;

    @NotBlank
    @Size(min = 0, max = 30)
    private String author;

}

Percebe agora como ficou a documentação do Schema de Book:

Gerando documentação adicional usando `@ControllerAdvice` e `@ResponseStatus`:

Usar @ResponseStatus em métodos em uma classe @RestControllerAdvice o openapi vai gerar automaticamente documentação para os códigos de resposta. Nesta classe @RestControllerAdvice, os dois métodos são anotados com @ResponseStatus:



import org.springframework.core.convert.ConversionFailedException;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@RestControllerAdvice
public class GlobalControllerExceptionHandler {

    @ExceptionHandler(ConversionFailedException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public ResponseEntity<String> handleConversion(RuntimeException ex) {
        return new ResponseEntity<>(ex.getMessage(), HttpStatus.BAD_REQUEST);
    }

    @ExceptionHandler(BookNotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public ResponseEntity<String> handleBookNotFound(RuntimeException ex) {
        return new ResponseEntity<>(ex.getMessage(), HttpStatus.NOT_FOUND);
    }
}

As a result, we can now see the documentation for the response codes 400 and 404:

Gerando documentação usando `@Operation` e `@ApiResponses`

A seguir, vamos ver como podemos adicionar alguma descrição à nossa API usando algumas anotações da especificação OpenAPI.

Para fazer isso, anotaremos o endpoint /api/book/{id} do nosso controlador com @Operation e @ApiResponses:



@Operation(summary = "Get a book by its id")
@ApiResponses(value = { 
  @ApiResponse(responseCode = "200", description = "Found the book", 
    content = { @Content(mediaType = "application/json", 
      schema = @Schema(implementation = Book.class)) }),
  @ApiResponse(responseCode = "400", description = "Invalid id supplied", 
    content = @Content), 
  @ApiResponse(responseCode = "404", description = "Book not found", 
    content = @Content) })
@GetMapping("/{id}")
public Book findById(@Parameter(description = "id of book to be searched") 
  @PathVariable long id) {
    return repository.findById(id).orElseThrow(() -> new BookNotFoundException());
}

Agora nosso endpoint /api/book/{id} ficou documentado assim:

Conclusão

Neste artigo, aprendemos como configurar o springdoc-openapi em nossos projetos. Em seguida, vimos como integrar springdoc-openapi com a UI do Swagger.

Depois disso, vimos como o springdoc-openapi gera documentação automaticamente usando anotações de validação de bean JSR 303 e as anotações @ResponseStatus na classe @ControllerAdvice.

Também aprendemos como adicionar uma descrição à nossa API usando algumas anotações específicas da OpenAPI

O springdoc-openapi gera documentação da API de acordo com as especificações do OpenAPI 3. Além disso, ele também cuida da configuração da UI do Swagger para nós, tornando a geração de documentos da API uma tarefa razoavelmente simples.

Referencias

5 ótimos livros NÃO modinha que vai ALÉM de linguagem e que você DEVERIA ler em 2023

Fabiano Góes • e-Programar — Wed, 11 Jan 2023 17:20:53 +0000

O projeto Fênix – Edição comemorativa: um romance sobre TI, DevOps e sobre ajudar o seu negócio a vencer.

Accelerate: The Science of Lean Software and DevOps: Building and Scaling High Performing Technology Organizations.

Engenharia de Software Moderna: Princípios e Práticas para Desenvolvimento de Software com Produtividade.

The Programmer's Brain: What Every Programmer Needs to Know about Cognition.

A Philosophy of Software Design.

E ai, já leu algum desses livros ?
Qual livro você indicaria pra entrar nessa lista ?

diz ai nos comentários.

Spring Rest Repositories para acelerar MVP e PoC

Fabiano Góes • e-Programar — Tue, 09 Aug 2022 23:25:00 +0000

1. O Problema que queremos resolver

As vezes precisamos criar um MVP e testar uma ideia rápido para ter feedback o quanto antes e é aqui que o Spring REST Repositories brilha acelerando muito o desenvolvimento de uma API REST.
Neste artigo vamos criar um CRUD de uma API REST utilizando alguns recursos muito interessantes no ecosistema Spring.

O que vamos usar:

Spring Data/JPA para fazer o trabalho duro de ORM e manipular os dados no Banco.
Spring REST Repositories para expor nosso CRUD através de uma API REST.
H2 como Banco de Dados Relacional em memória.
Lombok para automatizar nossos Getters, Setters, Constructors, ToString.

2. A Solução

Vamos usar o site SPRING INITIALIZR para criação do projeto, acesse a URL: https://start.spring.io/ e configure conforme a imagem e ao final clique em “Generate Project”

Na sessão de Dependences digite: Web, JPA, H2, Rest Repositories. Após clicar em “Generate Project” será feito o download do projeto em um arquivo .zip, descompacte e importe em sua IDE de preferencia.

Agora vamos criar nosso modelo “Person”, que neste caso será bem simple pois o Foco é o “Spring Rest Repositories”.

import lombok.Data;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;

@Data
@Entity
public class Person {

    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    private long id;

    private String firstName;
    private String lastName;

}

Aqui usamos algumas annotations:

Entity: do conhecido JPA para tornar nosso modelo um ORM.
Id: do JPA para setar nosso id como Chave primária.
GeneratedValue: do JPA para setar nosso id como AutoIncrement.
Data: do Lombok para criar nossos Getters and Setters.

Com nosso modelo ORM criado podemos criar nossa Interface Repository, e aqui está o pulo do gato onde acontece toda a Magia do Spring.

import java.util.List;
import org.springframework.data.repository.PagingAndSortingRepository;
import org.springframework.data.repository.query.Param;
import org.springframework.data.rest.core.annotation.RepositoryRestResource;

@RepositoryRestResource(collectionResourceRel = "people", path = "people")
public interface PersonRepository extends PagingAndSortingRepository<Person, Long> {

   List<Person> findByLastName(@Param("name") String name);

}

Aqui cabe alguns comentários:
Quem já está familiarizado com Spring Data sabe que é comum anotar essa Interface com @Repository e aqui estamos anotando com @RepositoryRestResource.
Com essa annotation o Spring irá fazer uma linda magia e apenas com essa interface ele já ira criar nossa camada de Repository que saberá receber nosso modelo Person e executar todas as tarefas de CRUD em nosso Banco de Dados, além disso ele criar uma camada de Controller internamente e irá expor esse nosso CRUD através de uma API REST.
Isso mesmo, não teremos que criar nem a nossa camada Service nem a nossa camada Controller, Automágicamente o Spring fará esse trabalha para nós através do Spring Rest Repositories =).
E ainda herdamos nossa interface de “PagingAndSortingRepository” que irá gerar nossas listas paginada, mais uma vez Automágicamente =).

Neste momento se executarmos nossa aplicação já temos uma API REST com todas as operações CRUD de Person além de um endpoint de consulta por “LastName”.

Aqui a lista de endpoints disponíveis na nossa API REST:

GET http://localhost:8080
GET http://localhost:8080/people
GET http://localhost:8080/people/{id}
GET http://localhost:8080/people/search
POST http://localhost:8080/people
PUT http://localhost:8080/people/{id}
PATCH http://localhost:8080/people/{id}
DELETE http://localhost:8080/people/{id}

PUT substitui um registro inteiro. Campos não fornecidos serão substituídos por null.
PATCH pode ser usado para atualizar um subconjunto de itens.

Segue alguns exemplos de Teste utilizando o curl.

POST:

$ curl -i -X POST -H "Content-Type:application/json" -d '{"firstName": "Frodo", "lastName": "Baggins"}' 


http://localhost:8080/people
HTTP/1.1 201 
Location: http://localhost:8080/people/1
Content-Type: application/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Mon, 04 Feb 2019 21:03:47 GMT
{
  "firstName" : "Frodo",
  "lastName" : "Baggins",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people/1"
    },
    "person" : {
      "href" : "http://localhost:8080/people/1"
    }
  }
}%

GET All:

$ curl http://localhost:8080/people  


{
  "_embedded" : {
    "people" : [ {
      "firstName" : "Frodo",
      "lastName" : "Baggins",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/people/1"
        },
        "person" : {
          "href" : "http://localhost:8080/people/1"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people{?page,size,sort}",
      "templated" : true
    },
    "profile" : {
      "href" : "http://localhost:8080/profile/people"
    },
    "search" : {
      "href" : "http://localhost:8080/people/search"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}%

Perceba neste exemplo que o resultado é paginado com: size, totalElements, totalPages, number.

Adicionando Swagger

Adicione as dependências no pom.xml

<!-- Swagger -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>3.0.0-SNAPSHOT</version>
</dependency>
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-data-rest</artifactId>
   <version>3.0.0-SNAPSHOT</version>
</dependency>
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>3.0.0-SNAPSHOT</version>
</dependency>

Adicione também no pom.xml o repositório da dependência:

<repositories>
   <repository>
      <id>jcenter-snapshots</id>
      <name>jcenter</name>
      <url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
   </repository>
</repositories>

É importante adicionar esse repository porque no repositório central ainda não tem essa versão do swagger, e é nela que estão implementando essa feature do Swagger para suportar o Spring Rest Repositories.

A classe Configuration do Swagger

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.data.rest.configuration.SpringDataRestConfiguration;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

@Configuration
@EnableSwagger2WebMvc
@Import(SpringDataRestConfiguration.class)
public class SwaggerConfiguration {

    private static final String PATH_MAPPING = "/";

    private static final String PACKAGE_BASE = "com.eprogramar.demorepositoryrestresource";

    @Value("${info.app.version}")
    private String projectVersion;

    @Value("${info.app.name}")
    private String projectName;

    @Value("${info.app.description}")
    private String projectDescription;

    @Value("${spring.profiles.active}")
    private String activeProfile;

    @Bean
    Docket rsApi() {
        return new Docket(DocumentationType.SWAGGER_12)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .pathMapping(PATH_MAPPING)
                .useDefaultResponseMessages(false);
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(projectName)
                .description(projectDescription + " - Profile: " + activeProfile)
                .version(projectVersion)
                .build();
    }

}

Adicionei algumas properties no application.properites só pra facilitar as coisas não seria uma coisa obrigatória.

Ok, executando a aplicação agora podemos ver todos os endpoints documentados, acesse: http://localhost:8080/swagger-ui.html

Veja Também meu video:
“Como Criar uma API Rest Kotlin com Persistencia e Paginação em 6 minutos”

3. Conclusão

Neste artigo aprendemos utilizar algumas magias do Spring onde ele automatizou a criação de nosso ORM e ainda criou nossa API REST automágicamente.
Com isso ganhamos muito tempo quando precisamos criar CRUD e expor através de uma API REST.
Claro, em caso simples onde não precisamos de regras para nosso CRUD isso pode ser uma boa opção, se combinar com Bean Validation para validar alguns campos e ainda utilizar de um Handle para interceptar os Erros e soltar uma mensagem mais amigável fica uma solução bem legal.
Em casos onde tem muitas regras ai é aconselhável utilizar o modelo mais conceitual com a Camada Service e Controller.

O código pode ser visto no Github:
https://github.com/e-programar/demo-repository-rest-resource

Referencia: https://spring.io/guides/gs/accessing-data-rest/

Desvendando o Spring Application Context

Fabiano Góes • e-Programar — Sat, 05 Feb 2022 18:55:00 +0000

Este é um Post bem teórico, mas se você já trabalha ou está interessando em conhecer um pouco sobre Spring Framework invista um tempinho para ler este conteúdo porque é extremamente importante.

O Spring Framework fornece um modelo abrangente de programação e configuração para aplicativos corporativos modernos baseados em Java em qualquer tipo de plataforma de implantação.
Um elemento chave do Spring é o suporte de infra-estrutura no nível do aplicativo: o Spring se concentra no “encanamento” dos aplicativos corporativos, para que as equipes possam se concentrar na lógica de negócios no nível do aplicativo, sem vínculos desnecessários a ambientes de implantação específicos.

Um pouco de História

Para quem está chegando no universo Java Web agora e já chega aprendendo Spring Boot não tem ideia de como era burocrático construir aplicações Web em Java antes.
Quando usávamos Java EE e queríamos delegar responsabilidades para um contexto mais global do seu código tínhamos que fazer isso usando um Servidor de Aplicação, se queríamos por exemplo usar um pool de conexão ou uma mensageria, tínhamos que usar os tais Servidores de Aplicação por exemplo: JBoss(Red Hat), WebSphere(IBM), WebLogic(Oracle) e isso tornava tanto o desenvolvimento quanto o processo de implantação bem burocrático.
Lógico que dependendo do Domínio que você estivesse desenvolvendo um Servidor de Aplicação era necessário, mas quando estava desenvolvendo uma aplicação simples isso era muito ruim, desde o setup de desenvolvimento até a implantação. Isso gerava uma curva de aprendizado bem grande quando as vezes queríamos apenas construir uma aplicação simples e implantar em um servidor simples também.
Na época já tínhamos o Tomcat que era bem simples de trabalhar, mas não era um Servidor de Aplicação e sim um WebServer e não implementava as tais features de um Servidor de Aplicação.
Ai nessa época veio o Spring Framework com essa proposta de subir um Contexto(Application Context) onde ele gerenciava objetos para sua aplicação, assim você poderia delegar tais responsabilidades para o Framework e se concentrar mais em suas Regras de Negócio, então conseguimos por exemplo usar as Injeções de Dependências do Spring e deixar a responsabilidade de gerenciar o ciclo de vida de Objetos em memoria para o Spring.
E agora conseguíamos usando o Spring Framework desfrutar de recursos de um Servidor de Aplicação usando apenas nosso querido Apache Tomcat. \o/

O tal de Aplication Context

Todo aplicativo Spring requer um Contexto, um local onde todos os componentes são registrados. Poderíamos pensar nisso como um diretório central de instâncias de objetos criados e armazenados. Quando usamos o Spring Framework e criamos algo, por exemplo, um conjunto de conexões, ele é registrado em nosso contexto ou quando criamos nossos próprios componentes(Beans, veja meu artigo Desvendando os Beans do Spring usando Kotlin) eles também serão registrados neste Contexto. Portanto, se em outra parte do aplicativo precisamos de um desses componentes, em vez de criá-lo novamente, podemos usa-lo dentro da instancia do Contexto(IoC).

Toda essa troca de responsabilidade funciona basicamente com as Annotations, usamos uma Annotation para dizer que o Spring deve se Auto Configurar(@EnableAutoConfiguration), uma outra Annotation para dizer onde o Spring deve procurar por possíveis Componentes(@ComponentScan), outras Annotations para dizer que o Spring deve se responsabilizar pela gerencia de estado deste Componente(@Component, @Service, @Repository, @Controller), e por fim quando queremos usar algum Componente desses que estão no tal Contexto usamos a Annotation @Autowired e com ela dizemos para o Spring que ele deve procurar em seu Contexto algum Componente equivalente ao que precisamos e Injetar na variável onde estamos usando essa Annotation, e essa foi uma das primeiras features que justificava o uso do Spring Framework que é: Spring IoC que está dentro do pacote Core Technologies do Spring.

Mas e a Configuração disso tudo ?

Bom, aqui tocamos em um ponto de muita discussão desde sempre no mundo Java, Os tais XML de configuração. Nessa época, mesmo com o surgimento do tão amado Spring Framework ainda existia muitas XMLs de configuração, o que ainda deixava tudo muito burocrático.
Tínhamos um servlet-context.xml onde precisávamos configurar um bocado de coisas e perdíamos muito tempo com isso.
Se tiver curiosidade, segue um exemplo bem resumido de um xml desse:

<?xml version="1.0" encoding="UTF-8"?>
<beans:beans xmlns="http://www.springframework.org/schema/mvc"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:beans="http://www.springframework.org/schema/beans"
    xmlns:context="http://www.springframework.org/schema/context"
    xmlns:tx="http://www.springframework.org/schema/tx"
    xsi:schemaLocation="http://www.springframework.org/schema/mvc http://www.springframework.org/schema/mvc/spring-mvc.xsd
        http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
        http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-3.1.xsd
        http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd">

    <annotation-driven />
    <resources mapping="/resources/**" location="/resources/" />
    <beans:bean
        class="org.springframework.web.servlet.view.InternalResourceViewResolver">
        <beans:property name="prefix" value="/WEB-INF/views/" />
        <beans:property name="suffix" value=".jsp" />
    </beans:bean>
    <context:component-scan base-package="com.eprogramar.springjpa com.eprogramar.springjpa.dao" />
    <beans:bean class="org.springframework.dao.annotation.PersistenceExceptionTranslationPostProcessor"></beans:bean>
    <beans:bean id="entityManagerFactory" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
        <beans:property name="dataSource" ref="dsSpringJPA" />
        <beans:property name="jpaVendorAdapter">
            <beans:bean class="org.springframework.orm.jpa.vendor.HibernateJpaVendorAdapter" />
        </beans:property>
    </beans:bean>
    <beans:bean id="dsSpringJPA" class="org.apache.commons.dbcp.BasicDataSource">
        <beans:property name="driverClassName" value="com.mysql.jdbc.Driver" />
        <beans:property name="url" value="jdbc:mysql://localhost:3306/test" />
        <beans:property name="username" value="root" />
        <beans:property name="password" value="123" />
    </beans:bean>
    <tx:annotation-driven />
    <beans:bean id="transactionManager" class="org.springframework.orm.jpa.JpaTransactionManager">
        <beans:property name="entityManagerFactory" ref="entityManagerFactory" />
    </beans:bean>
</beans:beans>

Então tínhamos que configurar XML para o Contexto do Spring, XML para configuração de JPA/Hibernate, e isso era de fato muito burocrático, até a chegada do Spring Boot(Deus abençoe o Spring Boot) ai sim as coisas começaram a ficar produtivas e divertidas no desenvolvimento Java principalmente para a Aplicações Web.

Spring Boot merece um artigo dedicado a ele e vou tentar fazer isso em breve, por hora quero apenas trazer minha humilde opinião sobre quem viveu essa evolução e pode desfrutar dos ganhos de verdade. Isso é bem diferente de quem chega hoje e pega a coisa toda pronta.

Dito isso, quero finalizar ilustrando a configuração necessário hoje com o Spring Boot, esse é um exemplo utilizando Spring em uma aplicação Kotlin.

Se olharmos essa Annotation @SpringBootApplication por dentro veremos que ela tem outras Annotations bem interessantes por exemplo a @ComponentScan que é responsável por dizer para o Spring, onde ele deve procurar por Classes que devem ser gerenciadas como um Bean e devem ser registradas no Application Context.

Uma vez que temos o Entrypoint de nossa aplicação anotada com @SpringBootApplication, o Spring usará como ponto de partida para fazer o Scan, e todas os pacotes desse nível para dentro serão escaneados em busca de possíveis Beans, e você pode usar a Annotation @ComponentScan para customizar e ensinar o Spring à procurar por Beans em outros pacotes, por exemplo em libs que você possa estar usando dentro de sua empresa.

Conclusão

O Spring Application Context é uma peça fundamental dentro do ecossistema do Framework e é muito importante o desenvolvedor entender como ele funciona uma vez que decide usar esse fantástico framework que o Spring.
Esse foi um artigo bem teórico mas muito necessário, espero que gostem e que seja útil no seu desenvolvimento como Programador.
um forte abraço e até a próxima.

Referências

API REST ?

Fabiano Góes • e-Programar — Sat, 31 Jul 2021 23:35:01 +0000

Mas e o protocolo HTTP que é a base para a API REST você conhece ?

O Protocolo

API = Application Programming Interface
REST = Representational State Transfer

Basicamente a API REST foi criada para possibilitar a comunicação entre sistemas, e para que seja possível essa comunicação precisamos de um Protocolo, e é ai que entra o HTTP.

Funcionamento

HTTP utiliza o modelo Cliente-Servidor, como a maioria dos protocolos de rede, baseando-se no paradigma de Requisição e Resposta.

Um programa requisitante (Cliente) estabelece uma conexão com um outro programa receptor (Servidor) e envia-lhe uma requisição, contendo a URI, a versão do protocolo, uma mensagem MIME contendo os modificadores da requisição, informações sobre o cliente e, possivelmente, o conteúdo no corpo da mensagem.

O Servidor processa a Requisição(Request) e Responde(Responnse) com um Status incluindo sua versão de protocolo e com os códigos de erro informando se a operação foi bem sucedida ou não.
Após o envio da resposta pelo servidor, encerra-se a conexão estabelecida.

A Mensagem

Uma Mensagem, tanto de Requisição(Request) quanto de Resposta(Response), é composta por: Cabeçalhos(header) e Corpo(body).

Toda Requisição(Request) é enviada através de um Comando ou Métodos HTTP e os mais comum são:

POST
GET
PUT
PATCH
DELETE

Toda Resposta(Response) segue com um Código de Estado(HTTP Status) exemplos:

200(OK)
404(Not Found)
500(Internal Server Error)

Content-Type

Quando uma mensagem HTTP tiver um corpo, poderão ser incluídos cabeçalhos de entidades que descrevem suas características, como por exemplo, o Content-Type que informa o tipo MIME dos dados no corpo da mensagem.
Alguns tipos MIME:

text/plain(Arquivo no formato Texto ASCII)
text/html(Arquivo no formato HTML, utilizado como padrão para documentos Web)
image/gif(Imagem no formato GIF)
image/jpeg(Imagem no formato JPEG)
application/zip(Arquivo compactado)
application/json(Arquivo no formato JSON)
application/xml(Arquivo no formato XML)

O formato application/json é um formato muito utilizado em API REST.

Conceitos

A intenção aqui foi fazer apenas uma breve abordagem sobre os Conceitos por traz de API REST.

Entendendo a base HTTP e o problema que a API REST se propõe a resolver, conseguimos utilizar as Linguagens de Programação e Frameworks de fato como ferramentas para resolvermos um problema.

E a base sempre será a mesma independente de Linguagem ou Framework.

Deixei seu comentário sobre o que achou do Post, compartilhe em suas redes e ajude a fortalecer uma comunidade onde juntos somos mais fortes!

Desvendando os Beans do Spring usando Kotlin

Fabiano Góes • e-Programar — Thu, 17 Jun 2021 18:18:00 +0000

Tenho visto pessoas usando o Spring Framework de forma totalmente mecânica, sem saber O QUE e O POR QUÊ decoram as classes com as Annotations: @Controller, @RestController, @Service, @Repository, @Component e etc.
Hoje vamos entender um pouco sobre o que acontece por traz dessas Annotations.

O que acontece na prática, é que decoramos que devemos estruturar nosso projeto com os seguintes packages: controller, service, repository.

E que toda classe no package controller deve ser anotada com @Controller ou @RestController.
Toda classe no package service deve ser anotada com @Service.
Toda classe no package repository deve ser anotada com @Repository.

E as classes de modelo que ficam no package model não precisam ser anotadas

Então, quando precisamos usar algumas dessas classes anotadas, usamos o mágico @Autowired.
Com isso em mente, usamos uma IDE ou o site Spring Initializr para criar nossos projetos, aplicamos a ideia acima de packages e Annotations e voilà, tudo funciona magicamente, bola pra frente, check no LinkedIn que manjo tudo de Spring Framework ;)

E de verdade, não vejo problema em começar assim, acho legal começar simplesmente codando e vendo as coisas funcionarem, mas acho que na sequencia, é preciso se esforçar um pouquinho para entender o que aconteceu e o que exatamente o Framework resolveu para nós.

Component Scan

Bom, dado o problema, vamos tentar esclarecer um pouco as coisas.
Quando criamos um projeto usando Spring como Framework Web, durante o Boot da aplicação existem alguns processos que o Spring executa para preparar esse ambiente, e um desses processo se chama "Component Scan".
Na prática, o Spring Escaneia nossos pacotes em busca de classes Anotadas com Estereótipos: @Component e suas especializações como @Controller, @RestController, @Service, @Repository.

Podemos usar a Annotation @ComponentScan para customizar onde queremos que o Spring procure classes Beans.

@ComponentScan("com.example.demo")
class MyCustomScan {}

Cada classe que o Spring encontrar, ele vai registrar em um Container chamado "ApplicationContext", a partir daí essa classe virou um Bean.
O que ele faz é tentar instanciar essas classes e adicioná-las em uma lista de Bean (Spring-managed).
Então ele passa por todos os @Autowired e procura em sua lista de Beans algum Bean que equivalente.
Assim sua aplicação sobe com as classes magicamente instanciadas e Injetadas.

The IoC container

O Spring Framework aplica o princípio de Inversão de Controle IoC (Inversion Of Control). IoC também é conhecido como injeção de dependência (DI). É um processo pelo qual os objetos definem suas dependências, ou seja, os outros objetos com os quais trabalham, apenas por meio de argumentos do construtor, argumentos para um método de fábrica ou propriedades que são definidas na instância do objeto após serem construídas ou retornadas a partir de um método de fábrica. O contêiner injeta essas dependências quando criar o Bean. Esse processo é fundamentalmente o inverso, daí o nome Inversion of Control (IoC), do próprio Bean que controla a instanciação ou localização de suas dependências, usando a construção direta de classes ou um mecanismo como o padrão Service Locator.

Aqui vale uma observação importante: é uma boa prática programar para Interface e não para Implementações, assim mantendo suas classes com baixo acoplamento.
Então, onde queremos Injetar nossas classes com @Autowired criamos as variáveis ou parâmetros do tipo da Interface e não da Implementação, ai o Spring tem o trabalho de encontrar algum Bean que implemente aquela Interface para então injetar.

Exemplo prático

interface PersonService {
    fun findAll()
}
@Service
class PersonServiceImpl : PersonService {
    override fun findAll() {
        println("Returning all people")
    }
}
@RestController
@RequestMapping("/people")
class PersonController {

    @Autowired
    lateinit var personService: PersonService

    @GetMapping
    fun findAll() = personService.findAll()
}

Neste exemplo criamos uma interface PersonInterface e implementamos essa interface através da classe PersonServiceImpl e anotamos a classe com @Service.
Então no controller PersonController pedimos para o Spring Injetar uma PersonService por meio do @Autowired.
Perceba que criamos a variável do tipo da Interface e não da classe e deixamos a critério do Spring encontrar em sua lista de Beans uma implementação equivalente.
Uma outra maneira de fazer essa Injeção de Dependência é usando o construtor invés de um atributo da classe, vamos ver como ficaria:

@RestControllerSpring-managed
@RequestMapping("/people")
class PersonController(val personService: PersonService) {

    @GetMapping
    fun findAll() = personService.findAll()
}

O QUE aconteceu até aqui ?

Quando executarmos nossa aplicação o Spring começará a fazer sua magia.
Passando pelo processo de Component Scan, ele perceberá que temos nossa classe PersonService anotada com @Service, irá instanciar essa classe e registrá-la em seu ApplicationContext, tornando nossa classe um Bean Spring-managed.

Então ele continua o processo e encontra na classe PersonController anotada com @RestController, logo ele sabe que precisa Instanciar essa classe e registrá-la no ApplicationContext. Porém, essa classe tem uma dependência em seu Construtor e ele percebe que essa dependência é uma Interface, então ele percorre sua lista de Beans, em busca de alguém que implemente essa Interface. Encontra nossa implementação PersonServiceImpl e aplica a IoC | DI.

Perceba que não precisamos usar o @Autowired no construtor, e não teria problema em usar, funcionaria do mesmo jeito, mas o Spring é inteligente o suficiente para saber que para instanciar o PersonController ele precisa Injetar o PersonService que é uma dependência do construtor, até porque usamos val que irá criar um atributo da classe somente leitura e imutável, então é obrigatório a passagem do valor neste momento.
A partir daí o Contexto do Spring é carregado com nossas classes instanciadas e quem está controlando o ciclo de vida desses objetos é o próprio Spring.
Se você está atento a tudo o que aconteceu você deve ter se perguntado:
Mas e se eu tiver duas implementações da Interface PersonService, como o Spring saberia qual Injetar ???? :(

Vamos criar mais uma implementação e testar esse comportamento do Spring:

@Service
class CustomPersonServiceImpl : PersonService {
    override fun findAll() {
        println("CustomPersonServiceImpl - Returning all people")
    }
}

Se executarmos nossa aplicação, veja o comportamento do Spring:

Veja que foi lançado um Erro ao iniciar o ApplicationContext, ele encontrou nossas duas implementações e não soube o que fazer. Neste caso precisamos dizer para ele o que queremos, e perceba que ele até sugeriu uma solução que é anotar uma de nossas implementações com @Primary. Vamos fazer isso anotando nossa primeira implementação com @Primary.

@Primary
@Service
class PersonServiceImpl : PersonService {
    override fun findAll() {
        println("Returning all people")
    }
}

Agora se executarmos novamente nossa aplicação tudo estará funcionando.
Mas e quando precisarmos que ele Injete nossa segunda implementação??

@RestController
@RequestMapping("/custom-people")
class CustomPersonController(
        @Qualifier("customPersonServiceImpl") val personService: PersonService
) {
    @GetMapping
    fun findAll() = personService.findAll()
}

Criei um novo controller CustomPersonController e nele quero que seja injetado nossa segunda implementação de PersonService - CustomPersonServiceImpl.
Para isso usei a Annotation @Qualifier, passando como value o nome da implementação começando com LowerCase @Qualifier(“customPersonServiceImpl”).
Isso é possível porque quando o Spring está registrando os Beans no ApplicationContext, ele usa o próprio nome da classe começando com LowerCase, uma prática muito comum utilizado por qualquer programador que vem de Java.

Se quisermos customizar o nome de nossos Beans podemos passar como value da Annotation @Service(“myCustomPersonServiceImpl”) e depois usamos este mesmo nome no @Qualifier(“myCustomPersonServiceImpl”).

Poderíamos ir um pouco além do convencional, imagine que vc tem classes de domínio que você gostaria que o Spring usasse como um Bean Spring-managed, porém, você não quer acoplar seu domínio a nenhum Framework, então não quer anotar nenhum de suas classes de domínio com @Service ou @Component.

Vamos resolver isso:

interface PersonService {
    fun findAll()
}
class PersonServiceImpl : PersonService {
    override fun findAll() {
        println("PersonServiceImpl Returning all people")
    }
}

class CustomPersonServiceImpl : PersonService {
    override fun findAll() {
        println("CustomPersonServiceImpl - Returning all people")
    }
}

Tiramos as Annotations @Service e agora nossas classes de Serviço/Domínio não estão acopladas ao Spring.
Mas queremos que em algum momento, o Spring registre elas no ApplicationContext para ser injetada em algum lugar fora da nossa camada de Domínio, por exemplo na camada de Controller.

@Configuration
class PersonConfiguration {

    @Primary
    @Bean
    fun personServiceImpl(): PersonService = PersonServiceImpl()

    @Bean
    fun customPersonServiceImpl(): PersonService =    CustomPersonServiceImpl()
}

Criamos uma classe de configuração anotando com @Configuration, onde usamos a Annotation @Bean sobre uma function que tem como tipo de retorno nossa Interface.
Só que em cada um retornamos uma instância diferente e, por convenção, usamos o nome da function como o nome da classe começando com LowerCase, usando a mesma regra do Spring quando está registrando os Beans em seu ApplicationContext.

Então, agora quando acontecer o "Component Scan" ele perceberá que tem uma classe @Configuration que está solicitando para o Spring register alguns Beans no ApplicationContext.
A partir daí tudo volta a funcionar, mas resolvemos o problema de acoplamento do Framework em nossas classes de domínio e perceba que usamos novamente a Annotation @Primary para direcionar o Spring que quando ele encontrar uma Injection da nossa Interface PersonService sem um @Qualifier ele deve priorizar o Bean personServiceImpl.

Para finalizar, quero só explicar que as Annotations @Controller, @RestController, @Service, @Repository são todas especializações de @Component:

@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Component
public @interface Controller {
  ...
}
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Component
public @interface Service {
  ...
}
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Component
public @interface Repository {
   ...
}

O que são apenas stereotype para deixar mais explícito o que as classes anotadas com elas quer tratar:

Service = Business
Repository = Data
Controller = Web

E em alguns casos, por exemplo, @Repository o Spring vai tratar diferente as Exceptions.
Uma vantagem de usar esta anotação é que ela possui a tradução automática de exceção de persistência ativada.
E ao usar uma estrutura de persistência como o Hibernate, as exceções ativas lançadas usarão classes anotadas com @Repository para lançar automaticamente convertidas em subclasses do DataAccessExeption do Spring.

O POR QUÊ devemos usar tudo isso ?

Isso é importante para podermos tirar um maior proveito do Framework que estamos utilizando.
Assim, usamos o Framework para resolver problemas de implementação de alguns Patterns, por exemplo MVC, IoC/DI, DAO/Repository, e ainda deixamos a cargo do Framework a responsabilidade de gerenciar o Ciclo de Vida dos nossos Objetos/Beans.

Com isso conseguimos deixar nosso código mais coeso e menos acoplado melhorando o Design do Software e ainda facilitando a implementação de Tests Automatizados.
Se entrarmos mais a fundo na questão do Spring Boot em volta de tudo isso temos muito mais problemas resolvidos tornando nosso dia-a-dia como Desenvolvedores muito mais produtivo.

Bom, se você chegou até aqui você foi muito guerreiro porque foi um Post bem teórico, mas como mencionei lá no começo, alguns momentos é preciso entender O QUE estamos fazendo e O POR QUÊ estamos fazendo determinadas coisas em nossos sistemas.

Espero que este Post seja útil para melhorar seu entendimento sobre Spring Framework.

Um abraço e até a próxima.

Referencias

java #kotlin #spring #springframework #springboot #jvm #beans

DEV Community: Fabiano Góes • e-Programar

Documentando uma API REST Spring Boot 3 usando OpenAPI 3.0

Visão Geral

Configuração

Integração com UI Swagger

Support for swagger-ui Properties

API de exemplo

Repositório de exemplo

Modelo de exemplo

Application Properties de exemplo

Testando

Geração automática de documentos usando validação de bean JSR-303

Gerando documentação adicional usando @ControllerAdvice e @ResponseStatus:

Gerando documentação usando @Operation e @ApiResponses

Conclusão

Referencias

5 ótimos livros NÃO modinha que vai ALÉM de linguagem e que você DEVERIA ler em 2023

Spring Rest Repositories para acelerar MVP e PoC

1. O Problema que queremos resolver

2. A Solução

Adicionando Swagger

3. Conclusão

Desvendando o Spring Application Context

Um pouco de História

O tal de Aplication Context

Mas e a Configuração disso tudo ?

Conclusão

Referências

API REST ?

Mas e o protocolo HTTP que é a base para a API REST você conhece ?

O Protocolo

Funcionamento

A Mensagem

Content-Type

Conceitos

Desvendando os Beans do Spring usando Kotlin

Component Scan

The IoC container

Exemplo prático

O QUE aconteceu até aqui ?

O POR QUÊ devemos usar tudo isso ?

Referencias

java #kotlin #spring #springframework #springboot #jvm #beans

Gerando documentação adicional usando `@ControllerAdvice` e `@ResponseStatus`:

Gerando documentação usando `@Operation` e `@ApiResponses`