Arquivo para maio de 2016

Criando um Archetype Maven a partir de um projeto existente


Maven archetypes são templates de projetos que possibilitam iniciar o desenvolvimento de novos projetos rapidamente baseando se em uma base de arquivos, xml’s e classes já existentes. Um bom exemplo disso são os archetypes da fundação JBoss que possibilitam a criação de uma enorme variedade de arquiteturas para esse ambiente. Você pode por exemplo criar uma aplicação JEE em questão de minutos apenas executando um simples comando. No meu caso eu vou criar um template de uma API RESTful para que eu possa criar novas aplicações com esse comportamento com maior rapidez no futuro. A estrutura do nosso archetype será construido a partir do projeto Erudio API OAUTH2 que é uma aplicação RESTful com Spring Boot.


Existem duas formas de se criar um archetype Maven:


1. Construir o template do zero adicionando os arquivos necessários
2. Executar o Maven archetype plugin em um projeto já existente e configurá-lo. No nosso caso escolheremos a segunda opção.


Primeiro precisamos navegar até o diretório raiz do nosso projeto fonte e executamos o comando abaixo:


mvn archetype:create-from-project


Depois de toda a mágica você deverá ver uma tela de sucesso similar a imagem abaixo com a expressão “BUILD SUCCESS”. Note que a mensagem de sucesso aparece duas vezes, a primeira delas é referente a construção da estrutura do archetype e a segunda se refere a criação do mesmo.


[INFO] Scanning for projects...
Downloading: https://repo.spring.io/plugins-release/org/codehaus/mojo/maven-metadata.xml
Downloading: https://repo.spring.io/plugins-release/org/apache/maven/plugins/maven-metadata.xml
Downloaded: https://repo.spring.io/plugins-release/org/apache/maven/plugins/maven-metadata.xml (18 KB at 5.3 KB/sec)
Downloaded: https://repo.spring.io/plugins-release/org/codehaus/mojo/maven-metadata.xml (27 KB at 7.9 KB/sec)
Downloading: https://repo.spring.io/plugins-release/org/apache/maven/plugins/maven-archetype-plugin/maven-metadata.xml
Downloaded: https://repo.spring.io/plugins-release/org/apache/maven/plugins/maven-archetype-plugin/maven-metadata.xml (784 B at 0.9 KB/sec)
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building erudio-api-oauth2 0.1.0
[INFO] ------------------------------------------------------------------------
[INFO]
[INFO] >>> maven-archetype-plugin:2.4:create-from-project (default-cli) > generate-sources @ erudio-api-oauth2 >>>
[INFO]
[INFO] --- gmaven-plugin:1.5:generateStubs (default) @ erudio-api-oauth2 ---
[INFO] Generated 13 Java stubs
[INFO]
[INFO] <<< maven-archetype-plugin:2.4:create-from-project (default-cli) < generate-sources @ erudio-api-oauth2 <<<
[INFO]
[INFO] --- maven-archetype-plugin:2.4:create-from-project (default-cli) @ erudio-api-oauth2 ---
[INFO] Setting default groupId: br.com.erudio
[INFO] Setting default artifactId: erudio-api-oauth2
[INFO] Setting default version: 0.1.0
[INFO] Setting default package: br.com.erudio
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building erudio-api-oauth2-archetype 0.1.0
[INFO] ------------------------------------------------------------------------
[INFO]
[INFO] --- maven-resources-plugin:2.7:resources (default-resources) @ erudio-api-oauth2-archetype ---
[WARNING] Using platform encoding (Cp1252 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] Copying 116 resources
[INFO]
[INFO] --- maven-resources-plugin:2.7:testResources (default-testResources) @ erudio-api-oauth2-archetype ---
[WARNING] Using platform encoding (Cp1252 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] Copying 2 resources
[INFO]
[INFO] --- maven-archetype-plugin:2.4:jar (default-jar) @ erudio-api-oauth2-archetype ---
[INFO] Building archetype jar: D:\SandBox\MyCode\erudio-api-oauth2\target\generated-sources\archetype\target\erudio-api-oauth2-archetype-0.1.0
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 5.121 s
[INFO] Finished at: 2016-05-11T13:53:05-03:00
[INFO] Final Memory: 12M/121M
[INFO] ------------------------------------------------------------------------
[INFO] Archetype project created in D:\SandBox\MyCode\erudio-api-oauth2\target\generated-sources\archetype
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 27.668 s
[INFO] Finished at: 2016-05-11T13:53:06-03:00
[INFO] Final Memory: 30M/212M
[INFO] ------------------------------------------------------------------------
$


Acesse o diretório gerado target/generated-sources/archetype e copie o conteudo do pom.xml e da pasta src para um novo diretório caso necessário faça suas alterações.
A estrutura raiz do projeto deve ser similar a imagem abaixo:


Estrutura de Pastas


A pasta target pode ser deletada com o comando mvn clean. O pom.xml do archetype possui apenas o necessário para construir um novo projeto. Uma boa seria alterarmos a versão para 1.0-SNAPSHOT uma vez que ainda não é uma versão final.
Em src/ por sua vez estão os fontes do nosso archetype.
Continuem ligados e em uma próxima postagem explicarei como criar um novo projeto a partir do recém criado archetype.

Tags: , ,

Documentando aplicações REST com SpringBoot e Swagger



O Swagger é um dos frameworks mais usados para se documentar API’s REST. Ele facilita para que os clientes que consomem nossas API’s saibam quais os parâmetros nossas operações recebem, qual o retorno, o modelo, o media type retornado JSON, XML, CSV, binário etc. Sendo assim os clientes não precisam necessariamente discutir com a equipe de desenvolvimento da API sobre como usá-la. Pode-se dizer que a grosso modo o Swagger se comporta como o velho WSDL das aplicações SOAP. Sendo assim esse framework valoriza e muito nossas aplicações.


Tomando como base o projeto do post anterior vamos adicionar as configurações necessárias para habilitar o Swagger na aplicação. Para isso abra o arquivo pom.xml e adicione as tags destacadas com comentários no código abaixo.


<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	
	<groupId>br.com.erudio</groupId>
	<artifactId>simple-rest-example-swagger</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>1.3.3.RELEASE</version>
    </parent>
    
    <dependencies>
    	
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        
    	<!-- Adicionando a dependencia do Spring Boot Starter Actuator -->
    	<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-actuator</artifactId>
		</dependency>
		
		<!-- Adicione as dependências do Swagger API necessárias para gerar a documentação da aplicação-->
		<dependency>
			<groupId>com.mangofactory</groupId>
			<artifactId>swagger-springmvc</artifactId>
			<version>1.0.0</version>
		</dependency>
		<dependency>
			<groupId>org.ajar</groupId>
			<artifactId>swagger-spring-mvc-ui</artifactId>
			<version>0.4</version>
		</dependency>
		<dependency>
    		<groupId>org.apache.tomcat.embed</groupId>
    		<artifactId>tomcat-embed-jasper</artifactId>
    		<scope>provided</scope>
		</dependency>
		
    </dependencies>

    <properties>
        <java.version>1.8</java.version>
    </properties>
    
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
    
    <repositories>
        <repository>
            <id>spring-releases</id>
            <url>https://repo.spring.io/libs-release</url>
        </repository>
   		
   		<!-- Adicione o repositório do Swagger ao projeto-->
		<repository>
			<id>jcenter-release</id>
			<name>jcenter</name>
			<url>http://oss.jfrog.org/artifactory/oss-release-local/</url>
		</repository>
    </repositories>
    
    <pluginRepositories>
        <pluginRepository>
            <id>spring-releases</id>
            <url>https://repo.spring.io/libs-release</url>
        </pluginRepository>
    </pluginRepositories>
	
</project>



Feito isto precisamos alterar a classe Application para que ela acione o Swagger quando inicializar a aplicação.


package br.com.erudio;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.boot.builder.SpringApplicationBuilder;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;

import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
import com.mangofactory.swagger.models.dto.ApiInfo;
import com.mangofactory.swagger.plugin.EnableSwagger;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;

@Configuration // Define a classe como classe de configuração
@EnableAutoConfiguration // Habilita a autoconfiguração
@EnableSwagger //Habilita o Swagger
@ComponentScan(basePackages = {"br.com.erudio"}) //Escaneia todos os pacotes com o padrão br.com.erudio
public class Application {
    
	//Injeta uma instancia de SpringSwaggerConfig
    @Autowired
    private SpringSwaggerConfig swaggerConfig;
    
    public static void main(String[] args) {
		   //Troque esta linha SpringApplication.run(Application.class, args); pela linha abaixo
           new SpringApplicationBuilder(Application.class).web(true).run(args);
    }
    
    @Bean
    public SwaggerSpringMvcPlugin groupOnePlugin() {
       return new SwaggerSpringMvcPlugin(swaggerConfig)
			//Adiciona as configurações do Swagger ao SwaggerSpringMvcPlugin 
           .apiInfo(apiInfo()) //Adiciona as propriedades de configuração
           .includePatterns("/person.*?", "/greeting.*?") //Habilita o Swagger para os nossos 2 endpoints
           .swaggerGroup("admin");
    }
    
    private ApiInfo apiInfo() {
       ApiInfo apiInfo = new ApiInfo( //Configurações de contato, licença etc não nescessáriamente precisa ser definida
             "Swagger With Spring Boot",
             "This is a simple application to demonstrate how to work with Swagger in Spring Boot project!",
             "Free to use and mess around",
             "erudio@gmail.com",
             "Open Licence",
             "myemail@gmail.com"
       );
       return apiInfo;
    }
}



Agora que o Swagger já está configurado vamos documentar o endpoint Greeting.


package br.com.erudio.web.controllers;

import java.util.concurrent.atomic.AtomicLong;

import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestController;

import com.wordnik.swagger.annotations.Api;
import com.wordnik.swagger.annotations.ApiOperation;

import br.com.erudio.models.Greeting;

@Api(value = "greeting") //Diz ao Swagger que esse é um endpoint e REST deve ser documentado
@RestController
@RequestMapping("/greeting")
public class GreetingController {

    private static final String template = "Hello, %s!";
    private final AtomicLong counter = new AtomicLong();

	@ApiOperation(value = "Show Greeting Message" )
	 //Diz ao Swagger que essa operação REST deve ser documentado
	@ResponseStatus(HttpStatus.OK)
    @RequestMapping(method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_VALUE)
    public Greeting greeting(@RequestParam(value="name", defaultValue="World") String name) {
        return new Greeting(counter.incrementAndGet(), String.format(template, name));
    }
}



Como se pode ver é extremamente simples documentar a nossa API agora vamos vazer o mesmo com o endpoint Person.


package br.com.erudio.web.controllers;

import java.util.List;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestController;

import com.wordnik.swagger.annotations.Api;
import com.wordnik.swagger.annotations.ApiOperation;

import br.com.erudio.models.Person;
import br.com.erudio.services.PersonService;


@Api(value = "person") //Diz ao Swagger que esse é um endpoint e REST deve ser documentado
@RestController
@RequestMapping("/person/")
public class PersonController {
	
	@Autowired
	private PersonService personService;
	
	@ApiOperation(value = "Find person by ID" )
	//Diz ao Swagger que essa operação REST deve ser documentado
    @ResponseStatus(HttpStatus.OK)
    @RequestMapping(value = "/{personId}", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_VALUE)
    public Person get(@PathVariable(value = "personId") String personId){
        return personService.findById(personId);
    }
	
	@ApiOperation(value = "Find all persons" )
	//Diz ao Swagger que essa operação REST deve ser documentado
	@ResponseStatus(HttpStatus.OK)
	@RequestMapping(value = "/findAll", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_VALUE)
	public List<Person> findAll(){
		return personService.findAll();
	}
	
	@ApiOperation(value = "Create a new person" )
	//Diz ao Swagger que essa operação REST deve ser documentado
	@ResponseStatus(HttpStatus.OK)
	@RequestMapping(method = RequestMethod.PUT, consumes = MediaType.APPLICATION_JSON_VALUE, produces = MediaType.APPLICATION_JSON_VALUE)
	public Person create(@RequestBody Person person){
		return personService.create(person);
	}
	
	@ApiOperation(value = "Update an existing person")
	//Diz ao Swagger que essa operação REST deve ser documentado
	@ResponseStatus(HttpStatus.OK)
	@RequestMapping(method = RequestMethod.POST,consumes = MediaType.APPLICATION_JSON_VALUE)
	public Person update(@RequestBody Person person){
		return personService.update(person);
	}

	@ApiOperation(value = "Delete person by ID" )
	//Diz ao Swagger que essa operação REST deve ser documentado
	@ResponseStatus(HttpStatus.OK)
    @RequestMapping(value = "/{personId}", method = RequestMethod.DELETE)
    public void delete(@PathVariable(value = "personId") String personId){
        personService.delete(personId);
    }	
}



Não parece mas já terminamos toda a codificação necessária por adicionar o Swagger à nossa API mais uma vez acesse a classe Application e inicie a aplicação como no post anterior. Após inicializada a aplicação acesse a URL:


	localhost:8080/sdoc.jsp



Essa é a URL padrão da documentação e nunca tentei alterá-la. Ao acessá-la você verá algo similar a imagem abaixo documentando cada uma das operações dos nossos endpoints. Bastando clicar sobre cada uma para expandir e ver todos os detalhes da mesma.



postagem_3_1



Na imagem abaixo podemos ver a documentação da operação findAll. Temos a definição do modelo que ela nos retorna, o tipo de dados que ela retorna no caso JSON, os StatusCode que ela pode retornar, se clicarmos em Try Out o Swagger nos permite testar nossas operações. Ao executarmos esse teste a nossa API nos retornou um array de pessoas, o cabeçalho e o StatusCode 200 OK.



postagem_3_5


Chegamos com este post ao final da série de posts, práticos, sobre serviços REST. Você pode baixar o código deste post aqui e descompactar o arquivo zip e importar na sua IDE preferida ou clonar usando Git:

git clone https://github.com/leandrocgsi/simple-rest-example-swagger.git



Agora você já consegue dar os primeiros passos na criação de serviços REST, conhece conceitos, teóricos e práticos, básicos para executar esse tipo de tarefa. Sendo assim continue ligado no blog, por que no próximos posts iremos detonar o Rock’n Roll com outras tecnologias. É isso aí bons estudos.

Tags: , , , , ,