Resumen videos Spring Boot 101 Parte 1/4. Creación del proyecto, Web services y documentacion WS con JSONDoc

Después de seguir con gran deleite y algún tropiezo los magníficos videos de Spring de Dan Geabunea, con su seudónimo Romanian Coder, voy a realizar un pequeño resumen de lo mas imporante.

1. Creación de un proyecto Spring Boot con Eclipse WST

Para ello se hace

File-> New -> Eclipse Starter Project

Se le da nombre al proyecto en este caso springboot001,  y al grupo y paquete en mi caso le doy com.ximodante. a las alturas que estamos creo que es conveniente indicar la versión de Java la 1.8
y por la comodidad que da Maven, es conveniente elegirlo.

Se le da a Next y tenemos la siguiente pantalla

Y se eligen
1. Actuator que es un informador de la aplicación con múltiples indicadores
2. Thymeleaf que es un sistema de plantillas web
3. H2 como BD. Se podría elegir cualquier otra
4. Web para generar entornos web
5. JPA para la persistencia
6. Lombok para evitar la verbosidad de getters i setters

Si se hace por primera vez, no aparecereran con "Frequently Used", sinó  que se tendrá que buscarlos en cada una de sus categorías.

Ahora le damos al Finish y ya tenemos creado el proyecto.

Si entramos al eclipse WTS, ya podemos ver nuestro proyecto, y dentro del src/main/java, aparece nuestro paquete com.ximodante y dentro de él aparece la clase Springboot001Application que se puede ejecutar como "Spring Boot Application"

2. Indicación de las direcciones de acceso nuestro contenido web como servicio REST

Para ello vamos a utilizar las anotaciones;

@RestController:

que es una anotación de clase indicando que va a suministrar información web.

@RequestMapping(value ="/direccion_Contenido/{parametro}", method = RequestMethod.GET)):

Que es una anotación tanto de clase como de  método que especifica donde localizar el servicio REST. Cuando existe esta anatación tanto en la clase como en el método, entonces se concatena la dirección de la clase (como prefijo) a la del método para acceder a dicho método. 

Si indicamos parámetros, estos se especifican entre llaves.

Por omisión, se utiliza el método GET, pero para actualizar valores en un POJO es conveniente utilizar los convenios de REST para estos casos que es POST (hay algunos mas como DELETE, HEAD, PUT, TRACE..)

@PathVariable:

Es una anotación a nivel de parámetro del método para indicar que es el parámetro que se incluye en la dirección tal como se indica en el @RequestMapping con parámetro.  Veamos como queda una clase simple que solo saluda a un amigo cuyo nombre se lo pasamos como parámetro.

package com.ximodante;

import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping(value="/hello")
public class DemoController {
 
 @RequestMapping(value="/friend/{name}", method = RequestMethod.GET)
 public String HelloFriend(@PathVariable String name){
  return "Hello! You are my friend " + name + ". Nice to hear from you again!";
 }

}

3. Documentación de los servicios REST con JSONDoc

PASO 1:

Tal como se explicó en una entrada anterior para añadir una nueva dependencia a un proyecto con Maven, se procerá a añadir estas 2:

groupId:     org.jsondoc
artifactId:  spring-boot-starter-jsondoc

y

groupId:     org.jsondoc
artifactId:  jsondoc-ui-webjar

respecto a las versiones se puede consultar a Maven Repository y ver cual es la última

Si se quiere saber mas visitar la web de jsondoc.


PASO 2:

Ahora hay que inidicar en el fichero application.properties de la carpeta src/main/resources, las siguientes entradas

jsondoc.version=1.0
jsondoc.basepath=http://localhost:8080
jsondoc.packages[0]=com.ximodante


Y Indicando que versión es, que PATH es el que se utiliza y en que paquete java se encuentra la clase a utilizar.

PASO 3:

Ahora a la clase principal SpringBoot001Application.java hay que darle esta anotación

@EnableJSONDoc 

quedando

codigo java

package com.ximodante;

import org.jsondoc.spring.boot.starter.EnableJSONDoc;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
@EnableJSONDoc
public class Springboot001Application {

 public static void main(String[] args) {
  SpringApplication.run(Springboot02Application.class, args);
 }
}

fin codigo java


PASO 4:  Y la clase anterior en cuestión hay que nutrirla con las siguientes anotaciones de JSONDoc

@API (name="nombre", description="descripcion del WS", stage = ApiStage.RC):

Que es una anotación de clase indicando el nombre de la API, descripción de web service y en que estado esta (si deprecada etc)

@ApiMethod( description = "descripción del método"):

Que es una anotación de método donde se indica que hace

@ApiPathParam(name="name"):

Que es una anotación de parámetro del método  que utilizamos

Por tanto nuestra clase queda

package com.ximodante;

import org.jsondoc.core.annotation.Api;
import org.jsondoc.core.annotation.ApiMethod;
import org.jsondoc.core.annotation.ApiPathParam;
import org.jsondoc.core.pojo.ApiStage;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping(value="/hello")
@Api( name = "Greeting API",
      description = "Provides methods for greeting friends.",
      stage =ApiStage.RC)


public class DemoController {
 
 @RequestMapping(value="/friend/{name}", method = RequestMethod.GET)
 @ApiMethod( description = "Greets friend by name")
 public String HelloFriend(@ApiPathParam(name="name") @PathVariable String name){
  return "Hello! You are my friend " + name + ". Nice to hear from you again!";
 }

}

PASO 5: 

Comprobamos

Ejecutamos nuestra classe principal SpringBoot001Application.java como Spring Boot Application

Abrimos el navegador con la direccion http://localhost:8080/jsondoc-ui.html

Le indicamos el parámetro http://localhost:8080/jsondoc y nos aprece esta pantalla con la documetación de los servicios REST. Cada uno que juegue con ella y pruebe a realizarlos desde esta gtran utilidad.