Category Archives: Web

Testeando y documentando REST WS con Spring REST Docs

El presente post se centra en el uso de Spring REST Docs, un componente de la suite de Spring, que tiene como objetivo facilitar la generación de documentación de servicios web tipo REST.

Esta parte de Spring se integra con Spring MVC Test para que, desde nuestros tests de unidad o de integración, podamos, a la vez que se testean los servicios web, generar una documentación en formato HTML completa, consistente y moderna con la que describir el uso de los mismos.

Qué cocinamos

El uso de servicios web es una buena manera de compartir funcionalidades entre aplicaciones, crear interacciones entre ellas e integrar diferentes usos. Es una manera sencilla y poco invasiva de compartir información y realizar peticiones de ejecución de todo tipo de servicios. Además los servicios web tipo REST son sencillos de implementar, siguen estándares bien definidos y son compatibles entre multitud de aplicaciones y tipos de tecnologías.

Uno de los principales problemas a la hora de compartir o publicar un conjunto de servicios web tipo REST para que puedan ser usados por terceros es documentarlos debidamente para que esas terceras partes conozcan como usarlos, que invocar, que entradas de datos deben usar o que salidas deben esperar. Si otros tipos de servicios similares, como los servicios web tipo SOAP tienen documentos más o menos formales y estandarizados como los WSDL, que pueden ser usados por aplicaciones de terceros para crear clientes que invoquen a nuestros servicios, practicamente de forma automática, en el caso de los servicios tipo REST, su simplicidad y fundamentos basados en tecnologías más genéricas impide o dificulta la presencia de ese tipo de formalismos (aunque existen intentos para definir formalmente este tipo de servicios de forma similar usando también XML).

Al final, lo que parece ser una ventaja del mundo de los WS tipo REST, en relación a su simplicidad, puede verse como un problema a la hora de transmitir su uso a terceros. Por este motivo, se recomiendan, además de usar una serie de estándares o buenas prácticas a la hora de desarrollar los servicios, unas buenas prácticas asimismo a la hora de documentarlos. En este sentido, Spring REST Docs es una herramienta de gran utilidad ya que permite, al mismo tiempo que se testean esos mismos servicios web, generar una documentación de calidad. Además si se siguen esas recomendaciones y buenas prácticas, tendremos una documentación útil y sencilla de transmitir a terceros para que puedan hacer uso de nuestros servicios.

Lo que hace Spring REST Docs es generar, en función de la implementación que establezcamos en su ejecución, que puede realizarse integramente dentros de los tests de unidad o integración de nuestros servicios, una documentación en texto plano que posteriormente se transformará en HTML (u otros formatos) usando un programa externo llamado Asciidoctor. Para facilitar esto, existen plug-ins para Maven que permiten ejecutar los tests y generar la documentación de forma simultánea, de tal manera que incluso si la generación de documentación falla, el test también fallará, asegurándonos así que existe una referencia consistente para ese servicio.

Ingredientes

Vamos a usar una aplicación web de prueba que implementa una serie de servicios web tipo REST para pobar los Spring REST Docs, testeando y documentando dichos servicios de forma simultanea. Para ello necesitaremos:

Spring Boot
Spring MVC
Spring Data
Spring REST Docs
HSQLDB
Log4j

Para más información acerca de las dependencias usadas (versiones, paquetes específicos etc.) se puede echar un vistazo al pom.xml que se incluye con el proyecto.

Paso a paso

Lo de siempre, una vez creado nuestro proyecto, se maveniza. Este es el aspecto del pom.xml que incluye las dependencias a las librerias de los componentes anteriores:

<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>SpringRestDocs</groupId>
  <artifactId>SpringRestDocs</artifactId>
  <version>1.0</version>

  <parent>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-parent</artifactId>
      <version>1.3.1.RELEASE</version>
  </parent>

  <dependencies>
      <!-- Add typical dependencies for a web application -->
      <dependency>
          <groupId>org.springframework.boot</groupId>
          <artifactId>spring-boot-starter-web</artifactId>
      </dependency>

      <!-- Add typical dependencies for a spring JPA -->
      <dependency>
          <groupId>org.springframework.boot</groupId>
          <artifactId>spring-boot-starter-data-jpa</artifactId>
      </dependency>

      <!-- REST docs and MockMVC dependencies -->
      <dependency>
          <groupId>org.springframework.restdocs</groupId>
          <artifactId>spring-restdocs-mockmvc</artifactId>
          <version>1.0.1.RELEASE</version><!--$NO-MVN-MAN-VER$-->
       </dependency>

      <!-- Add typical dependencies for HSQLDB -->
      <dependency>
          <groupId>org.hsqldb</groupId>
          <artifactId>hsqldb</artifactId>
      </dependency>

      <!-- Use Log4j instead of default logging -->
          <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
            <exclusions>
                <exclusion>
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-starter-logging</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-log4j</artifactId>
        </dependency>
  </dependencies>

  <build>
    <sourceDirectory>src</sourceDirectory>
    <plugins>
      <plugin>
        <artifactId>maven-compiler-plugin</artifactId>
        <configuration>
          <source>1.8</source>
          <target>1.8</target>
        </configuration>
      </plugin>

      <!-- Package as an executable jar -->
      <plugin>
          <groupId>org.springframework.boot</groupId>
          <artifactId>spring-boot-maven-plugin</artifactId>
          <configuration>
              <mainClass>net.luisalbertogh.springrestdocs.SpringRestDocs</mainClass>
          </configuration>
      </plugin>

      <!-- Surfire plugin - Plugin to execute Tests -->
      <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-surefire-plugin</artifactId>
          <configuration>
              <includes>
                  <include>**/*Test.java</include>
              </includes>
          </configuration>
      </plugin>

      <!-- Asciidoctor plugin - Plugin for REST documentation -->
      <plugin>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctor-maven-plugin</artifactId>
            <version>1.5.2</version>
            <executions>
                <execution>
                    <id>generate-docs</id>
                    <!-- Configured to include documentation within the executable JAR file -->
                    <phase>prepare-package</phase>
                    <goals>
                        <goal>process-asciidoc</goal>
                    </goals>
                    <configuration>
                        <sourceDirectory>src/docs/asciidoc</sourceDirectory>
                        <outputDirectory>${project.build.directory}/generated-docs/${project.version}</outputDirectory>
                        <backend>html</backend>
                        <doctype>book</doctype>
                        <attributes>
                            <snippets>${project.build.directory}/generated-snippets</snippets>
                        </attributes>
                    </configuration>
                </execution>
            </executions>
        </plugin>

        <!-- Resources plugin - Copy generated REST docs into output location to be included within the release -->
        <plugin>
            <artifactId>maven-resources-plugin</artifactId>
            <version>2.7</version><!--$NO-MVN-MAN-VER$-->
            <executions>
                <execution>
                    <id>copy-resources</id>
                    <phase>prepare-package</phase>
                    <goals>
                        <goal>copy-resources</goal>
                    </goals>
                    <configuration>
                        <outputDirectory>
                            ${project.build.outputDirectory}/static/docs/${project.version}
                        </outputDirectory>
                        <resources>
                            <resource>
                                <directory>
                                    ${project.build.directory}/generated-docs/${project.version}
                                </directory>
                            </resource>
                        </resources>
                    </configuration>
                </execution>
            </executions>
        </plugin>

    </plugins>
  </build>

  <!-- Add Spring repositories -->
  <!-- (you don't need this if you are using a .RELEASE version) -->
  <repositories>
      <repository>
          <id>spring-snapshots</id>
          <url>http://repo.spring.io/snapshot</url>
          <snapshots><enabled>true</enabled></snapshots>
      </repository>
      <repository>
          <id>spring-milestones</id>
          <url>http://repo.spring.io/milestone</url>
      </repository>
  </repositories>
  <pluginRepositories>
      <pluginRepository>
          <id>spring-snapshots</id>
          <url>http://repo.spring.io/snapshot</url>
      </pluginRepository>
      <pluginRepository>
          <id>spring-milestones</id>
          <url>http://repo.spring.io/milestone</url>
      </pluginRepository>
  </pluginRepositories>
</project>

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

<groupId>SpringRestDocs</groupId>

<artifactId>SpringRestDocs</artifactId>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-parent</artifactId>

<version>1.3.1.RELEASE</version>

</parent>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-web</artifactId>

</dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-data-jpa</artifactId>

</dependency>

<groupId>org.springframework.restdocs</groupId>

<artifactId>spring-restdocs-mockmvc</artifactId>

<version>1.0.1.RELEASE</version>

</dependency>

<groupId>org.hsqldb</groupId>

<artifactId>hsqldb</artifactId>

</dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter</artifactId>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-logging</artifactId>

</exclusion>

</exclusions>

</dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-log4j</artifactId>

</dependency>

</dependencies>

<build>

<artifactId>maven-compiler-plugin</artifactId>

</configuration>

</plugin>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-maven-plugin</artifactId>

<mainClass>net.luisalbertogh.springrestdocs.SpringRestDocs</mainClass>

</configuration>

</plugin>

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-surefire-plugin</artifactId>

</includes>

</configuration>

</plugin>

<groupId>org.asciidoctor</groupId>

<artifactId>asciidoctor-maven-plugin</artifactId>

<id>generate-docs</id>

<phase>prepare-package</phase>

<goals>

<goal>process-asciidoc</goal>

</goals>

<sourceDirectory>src/docs/asciidoc</sourceDirectory>

<outputDirectory>${project.build.directory}/generated-docs/${project.version}</outputDirectory>

<snippets>${project.build.directory}/generated-snippets</snippets>

</attributes>

</configuration>

</execution>

</executions>

</plugin>

<artifactId>maven-resources-plugin</artifactId>

<id>copy-resources</id>

<phase>prepare-package</phase>

<goals>

<goal>copy-resources</goal>

</goals>

${project.build.outputDirectory}/static/docs/${project.version}

</outputDirectory>

${project.build.directory}/generated-docs/${project.version}

</directory>

</resource>

</resources>

</configuration>

</execution>

</executions>

</plugin>

</plugins>

</build>

<id>spring-snapshots</id>

<url>http://repo.spring.io/snapshot</url>

</repository>

<id>spring-milestones</id>

<url>http://repo.spring.io/milestone</url>

</repository>

</repositories>

<id>spring-snapshots</id>

<url>http://repo.spring.io/snapshot</url>

</pluginRepository>

<id>spring-milestones</id>

<url>http://repo.spring.io/milestone</url>

</pluginRepository>

</pluginRepositories>

</project>

En este caso, como en otros expuestos en este blog, para facilitar la implementación y ejecución de la prueba, se usa Spring Boot. Para implementar una pequeña aplicacion de prueba que desarrolle una serie de servicios web con acceso a datos, se usa la integración de Spring MVC y Spring Data con Spring Boot, de esta manera podremos implementar una sencilla aplicacion de forma rápida y simple. Se usa HSQLDB como base de datos relacional embebida, que nos permitirá ejecutar las operaciones CRUD clásicas de persistencia de datos.

El resto del pom incluye, además, los plugin que se usarán para, desde Maven, ejecutar los tests y la generación de la documentación (con Asciidoctor).

1. Desarrollar la aplicación de prueba que implementa los servicios web

Vamos a desarrollar una aplicación muy sencilla que nos permita realizar las clásicas operaciones CRUD sobre una entidad concreta y poder acceder a esas operaciones mediante servicios web tipo REST. Nuestra aplicación va a realizar lo siguiente:

Insertar o actualizar un superheroe
Borrar un superheroe
Mostrar un superheroe
Mostrar la lista de superheroes

Para ello desarrollamos una aplicación por capas más o menos clásica que implemente los diferentes niveles de acceso a los datos:

Un POJO que representa la entidad “Superheroe”
Un DAO que por simplicidad solo implementará las operaciones CRUD anteriores
Un Controlador que implementará los servicios web

En este caso, como no hay lógica de negocio, y por simplicidad y porque el post está centrado en la generación de la documentación de los servicios web y no en el desarrollo de la aplicación en sí, nos saltaremos la capa de negocio o de servicios que debería tener este tipo de aplicaciones por capas.

2. POJO y DAO

El POJO representa la entidad que usaremos para la prueba, que como se ha mencionado antes, modela los datos de un superheroe cualquiera, con sus superpoderes, debilidades y demás características. Además de usarlo para la capa de persistencia, también usaremos la misma clase como DTO para transferir datos entre capas de negocio.

/**
 * @author lagarcia
 *
 */
@Entity
public final class Superhero {
    /** The name */
    @NotNull
    private String name;

    /** The super power */
    @NotNull
    private String power;

    /** The evil actitude */
    @NotNull
    private Boolean evil;

    /** The creation date and time */
    private LocalDateTime createdDate;

    /** The creator name */
    private String creator;

    /** The superhero weakness */
    @NotNull
    private String weakness;

    /**
     * Default constructor.
     */
    public Superhero() {
        /* Empty */
    }

    /**
     * Constructor with args.
     *
     * @param nameArg
     * @param powerArg
     * @param evilArg
     */
    public Superhero(String nameArg, String powerArg, Boolean evilArg) {
        name = nameArg;
        power = powerArg;
        evil = evilArg;
    }

    /**
     * @return the name
     */
    @Id
    public String getName() {
        return name;
    }

    /**
     * @param nameArg
     *            the name to set
     */
    public void setName(String nameArg) {
        name = nameArg;
    }

    /**
     * @return the power
     */
    public String getPower() {
        return power;
    }

    /**
     * @param powerArg
     *            the power to set
     */
    public void setPower(String powerArg) {
        power = powerArg;
    }

    /**
     * @return the isEvil
     */
    public Boolean isEvil() {
        return evil;
    }

    /**
     * @param evilArg
     *            the isEvil to set
     */
    public void setEvil(Boolean evilArg) {
        evil = evilArg;
    }

    /**
     * @return the createdDate
     */
    @CreatedDate
    public LocalDateTime getCreatedDate() {
        return createdDate;
    }

    /**
     * @param createdDateArg
     *            the createdDate to set
     */
    public void setCreatedDate(LocalDateTime createdDateArg) {
        createdDate = createdDateArg;
    }

    /**
     * @return the creator
     */
    @CreatedBy
    public String getCreator() {
        return creator;
    }

    /**
     * @param creatorArg
     *            the creator to set
     */
    public void setCreator(String creatorArg) {
        creator = creatorArg;
    }

    /**
     * @return the weakness
     */
    public String getWeakness() {
        return weakness;
    }

    /**
     * @param weaknessArg
     *            the weakness to set
     */
    public void setWeakness(String weaknessArg) {
        weakness = weaknessArg;
    }

    @Override
    public String toString() {
        /* Evil */
        String evilStr = "good";
        if (evil) {
            evilStr = "evil";
        }

        /* Creation date */
        String dateStr = "";
        if (createdDate != null) {
            dateStr = createdDate.format(DateTimeFormatter.ISO_LOCAL_DATE_TIME);
        }

        return "[" + dateStr + "][" + creator + "] My name is <b>" + name
                + "</b> and my super power is <b>" + power
                + "</b>. Do not panic, I am " + evilStr + ". I am afraid to "
                + weakness;
    }
}

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

/**

* @author lagarcia

@Entity

public final class Superhero {

/** The name */

@NotNull

private String name;

/** The super power */

@NotNull

private String power;

/** The evil actitude */

@NotNull

private Boolean evil;

/** The creation date and time */

private LocalDateTime createdDate;

/** The creator name */

private String creator;

/** The superhero weakness */

@NotNull

private String weakness;

/**

* Default constructor.

public Superhero() {

/* Empty */

}

/**

* Constructor with args.

* @param nameArg

* @param powerArg

* @param evilArg

public Superhero(String nameArg, String powerArg, Boolean evilArg) {

name = nameArg;

power = powerArg;

evil = evilArg;

}

/**

* @return the name

@Id

public String getName() {

return name;

}

/**

* @param nameArg

* the name to set

public void setName(String nameArg) {

name = nameArg;

}

/**

* @return the power

public String getPower() {

return power;

}

/**

* @param powerArg

* the power to set

public void setPower(String powerArg) {

power = powerArg;

}

/**

* @return the isEvil

public Boolean isEvil() {

return evil;

}

/**

* @param evilArg

* the isEvil to set

public void setEvil(Boolean evilArg) {

evil = evilArg;

}

/**

* @return the createdDate

@CreatedDate

public LocalDateTime getCreatedDate() {

return createdDate;

}

/**

* @param createdDateArg

* the createdDate to set

public void setCreatedDate(LocalDateTime createdDateArg) {

createdDate = createdDateArg;

}

/**

* @return the creator

@CreatedBy

public String getCreator() {

return creator;

}

/**

* @param creatorArg

* the creator to set

public void setCreator(String creatorArg) {

creator = creatorArg;

}

/**

* @return the weakness

public String getWeakness() {

return weakness;

}

/**

* @param weaknessArg

* the weakness to set

public void setWeakness(String weaknessArg) {

weakness = weaknessArg;

}

@Override

public String toString() {

/* Evil */

String evilStr = "good";

if (evil) {

evilStr = "evil";

}

/* Creation date */

String dateStr = "";

if (createdDate != null) {

dateStr = createdDate.format(DateTimeFormatter.ISO_LOCAL_DATE_TIME);

}

return "[" + dateStr + "][" + creator + "] My name is " + name

+ " and my super power is " + power

+ ". Do not panic, I am " + evilStr + ". I am afraid to "

+ weakness;

}

El DAO, por motivos de simplicidad, es una interfaz que se exitende del CrudRepository de Spring Data. De esta manera se implementan automaticamente las operaciones CRUD clásicas necesarias para nuestro ejemplo. Usaremos el nombre del superheroe como clave primaria de la entidad.

/**
 * @author lagarcia
 *
 */
public interface SuperheroDAO extends CrudRepository<Superhero, String> {
}

/**

* @author lagarcia

public interface SuperheroDAO extends CrudRepository<Superhero, String> {

}

3. Servicios web

Para implementar los servicios web en este caso usamos Spring MVC. Vamos a seguir en la medida de lo posible las recomendaciones y buenas prácticas en la implementación de servicios de este tipo. Estas recomendaciones afectan a varias características de los servicios, a saber:

URL del servicio
Método HTTP
Códigos HTTP de respuesta

A parte de esto, en nuestro caso, como vamos a invocar los servicios desde una página web, usaremos JSON para enviar y recibir los datos desde los mismos (se podría usar XML en su lugar).

Los servicios que vamos a implementar y sus características son los siguientes:

Inserta o modifica un superheroe

/**
     * Add a new superhero.
     *
     * @param sh
     *            - The new superhero
     * @return The response entity
     */
    @RequestMapping(value = "/superhero", method = RequestMethod.POST, consumes = MediaType.APPLICATION_JSON_VALUE)
    public ResponseEntity<Void> saveSuperhero(@RequestBody Superhero sh) {
        logger.info("Save a superhero");
        if (sh != null) {
            sh.setCreator("ADMIN");
            sh.setCreatedDate(LocalDateTime.now());
            this.getHeroDAO().save(sh);
            return new ResponseEntity<Void>(HttpStatus.CREATED);
        }

        return new ResponseEntity<Void>(HttpStatus.BAD_REQUEST);
    }

/**

* Add a new superhero.

* @param sh

* - The new superhero

* @return The response entity

@RequestMapping(value = "/superhero", method = RequestMethod.POST, consumes = MediaType.APPLICATION_JSON_VALUE)

public ResponseEntity<Void> saveSuperhero(@RequestBody Superhero sh) {

logger.info("Save a superhero");

if (sh != null) {

sh.setCreator("ADMIN");

sh.setCreatedDate(LocalDateTime.now());

this.getHeroDAO().save(sh);

return new ResponseEntity<Void>(HttpStatus.CREATED);

}

return new ResponseEntity<Void>(HttpStatus.BAD_REQUEST);

}

Inserta un nuevo superheroe, si éste no existe, o lo modifica con los datos enviados, si existe en función de su clave primaria (nombre).

Obtiene los datos de un superheroe concreto en función de su nombre

/**
     * Get a superhero.
     *
     * @param name
     *            - Superhero name
     *
     * @return A superhero PO
     */
    @RequestMapping(value = "/superhero/{name}", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_VALUE)
    public ResponseEntity<Superhero> getSuperhero(
            @PathVariable("name") String name) {
        logger.info("Get " + name + " superhero");
        Superhero sh = this.getHeroDAO().findOne(name);
        if (sh != null) {
            return new ResponseEntity<Superhero>(sh, HttpStatus.FOUND);
        }

        return new ResponseEntity<Superhero>(HttpStatus.NOT_FOUND);
    }

/**

* Get a superhero.

* @param name

* - Superhero name

* @return A superhero PO

@RequestMapping(value = "/superhero/{name}", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_VALUE)

public ResponseEntity<Superhero> getSuperhero(

@PathVariable("name") String name) {

logger.info("Get " + name + " superhero");

Superhero sh = this.getHeroDAO().findOne(name);

if (sh != null) {

return new ResponseEntity<Superhero>(sh, HttpStatus.FOUND);

}

return new ResponseEntity<Superhero>(HttpStatus.NOT_FOUND);

}

Borra un superheroe en función de su nombre

/**
     * Delete a superhero.
     *
     * @param name
     *            - Superhero name
     * @return The response entity
     * */
    @RequestMapping(value = "/superhero/{name}/delete", method = RequestMethod.DELETE)
    public ResponseEntity<Void> deleteSuperhero(
            @PathVariable("name") String name) {
        logger.info("Delete a superhero");
        if (name != null) {
            this.getHeroDAO().delete(name);
            return new ResponseEntity<Void>(HttpStatus.OK);
        }

        return new ResponseEntity<Void>(HttpStatus.BAD_REQUEST);
    }

/**

* Delete a superhero.

* @param name

* - Superhero name

* @return The response entity

* */

@RequestMapping(value = "/superhero/{name}/delete", method = RequestMethod.DELETE)

public ResponseEntity<Void> deleteSuperhero(

@PathVariable("name") String name) {

logger.info("Delete a superhero");

if (name != null) {

this.getHeroDAO().delete(name);

return new ResponseEntity<Void>(HttpStatus.OK);

}

return new ResponseEntity<Void>(HttpStatus.BAD_REQUEST);

}

Muestra la lista completa de superheroes

/**
     * Find all superheros.
     *
     * @return The superheros list.
     */
    @RequestMapping(value = "/superhero/find", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_VALUE)
    public ResponseEntity<List<Superhero>> findSuperhero() {
        List<Superhero> shList = (List<Superhero>) this.getHeroDAO().findAll();
        if (shList != null && !shList.isEmpty()) {
            return new ResponseEntity<List<Superhero>>(shList, HttpStatus.FOUND);
        }

        return new ResponseEntity<List<Superhero>>(HttpStatus.NOT_FOUND);
    }

/**

* Find all superheros.

* @return The superheros list.

@RequestMapping(value = "/superhero/find", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_VALUE)

public ResponseEntity<List<Superhero>> findSuperhero() {

List<Superhero> shList = (List<Superhero>) this.getHeroDAO().findAll();

if (shList != null && !shList.isEmpty()) {

return new ResponseEntity<List<Superhero>>(shList, HttpStatus.FOUND);

}

return new ResponseEntity<List<Superhero>>(HttpStatus.NOT_FOUND);

}

4. Tests de servicios y generación de documentación

El último paso es implementar los tests de integración de los servicios que además de testear la funcionalidad completa de los mismos, nos permitirá generar la documentación asociada según los criterios que indiquemos en dicha implementación.

Para testear los servicios web usamos MockMVC de Spring, que implementa un cliente HTTP que nos permite invocar dichos servicios y validar los códigos de respuesta HTTP recibidos así como el contenido de la respuesta.

/* Test & document - insert or update service */
            this.mockMvc.perform(
                    post("/superhero").contentType(MediaType.APPLICATION_JSON)
                    .content(this.objectMapper.writeValueAsString(sh)))
                    .andExpect(status().isCreated());

...

/* Test & document - get a superhero service */
            this.mockMvc.perform(
                    get("/superhero/Spiderman").accept(
                            MediaType.APPLICATION_JSON)).andExpect(
                    status().isFound());

/* Test & document - insert or update service */

this.mockMvc.perform(

post("/superhero").contentType(MediaType.APPLICATION_JSON)

.content(this.objectMapper.writeValueAsString(sh)))

.andExpect(status().isCreated());

...

/* Test & document - get a superhero service */

this.mockMvc.perform(

get("/superhero/Spiderman").accept(

MediaType.APPLICATION_JSON)).andExpect(

status().isFound());

Al mismo tiempo inicializamos la generación de la documentación usando la API de Spring REST Docs y especificamos los campos obligatorios de entrada de datos o los campos de los datos de retorno para los servicios relacionados.

/** REST docs configuration */
    @Rule
    public final RestDocumentation restDocumentation = new RestDocumentation(
            "target/generated-snippets");

    /** REST document handler */
    private RestDocumentationResultHandler document;

....

/* Document constraints and request fields */
            ConstrainedFields fields = new ConstrainedFields(Superhero.class);

            this.document
                    .snippets(requestFields(
                            fields.withPath("name").description(
                                    "The superhero name"),
                            fields.withPath("power").description(
                                    "The superhero power"),
                            fields.withPath("creator").description(
                                    "The creator name"),
                            fields.withPath("createdDate").description(
                                    "The creation date"),
                            fields.withPath("evil").description(
                                    "Is the superhero evil?"),
                            fields.withPath("weakness").description(
                                    "The superhero weakness")));

/** REST docs configuration */

@Rule

public final RestDocumentation restDocumentation = new RestDocumentation(

"target/generated-snippets");

/** REST document handler */

private RestDocumentationResultHandler document;

....

/* Document constraints and request fields */

ConstrainedFields fields = new ConstrainedFields(Superhero.class);

this.document

.snippets(requestFields(

fields.withPath("name").description(

"The superhero name"),

fields.withPath("power").description(

"The superhero power"),

fields.withPath("creator").description(

"The creator name"),

fields.withPath("createdDate").description(

"The creation date"),

fields.withPath("evil").description(

"Is the superhero evil?"),

fields.withPath("weakness").description(

"The superhero weakness")));

5. Asciidoctor

Definimos en un fichero de texto plano el contenido y el formato de la página HTML que se generará como índice de nuestra documentación. Para ello usamos la sintaxis de Asciidoctor. Además seguimos recomendaciones de buenas prácticas relacionadas con la redacción de este tipo de documentación, a saber:

Indicar en un apartado diferente los distintos tipos de códigos de respuesta HTTP y su significado
Indicar en un apartado diferente los tipos de métodos HTTP usados y su significado
Indicar el tipo de respuesta recibida cuando se generar un error
Para cada servicio web documentado, indicar un ejemplo de invocación de la URL usando curl, ejemplos de petición y respuesta HTTP y si fuera necesario, el significado de los campos de entrada y salida de los datos usados. Esta información es la que genera de forma automática Spring REST Docs en cualquier caso, salvo la descripción de los campos de entrada y/o salida, que tendríamos que especificar en cada test si queremos que se genere

= Spring REST Docs API
luisalbertogh <luisalbertogh@hotmail.com>
:doctype: book
:toc:
:sectanchors:
:sectlinks:
:toclevels: 4
:source-highlighter: highlightjs

[[overview]]
= Overview

[[overview-http-verbs]]
== HTTP verbs

RESTful SpringRestDocs tries to adhere as closely as possible to standard HTTP and REST conventions in its
use of HTTP verbs.

|===
| Verb | Usage

| `GET`
| Used to retrieve a resource

| `POST`
| Used to create (add or update) a new resource

| `DELETE`
| Used to delete an existing resource
|===

[[overview-http-status-codes]]
== HTTP status codes

RESTful SpringRestDocs tries to adhere as closely as possible to standard HTTP and REST conventions in its
use of HTTP status codes.

|===
| Status code | Usage

| `200 OK`
| The request completed successfully

| `201 Created`
| A new resource has been saved (created or updated) successfully.
// The resource's URI is available from the response's `Location` header

| `302 Found`
| The searched resource was successfully found

| `400 Bad Request`
| The request was malformed. The response body will include an error providing further information

| `404 Not Found`
| The requested resource did not exist
|===

[[overview-errors]]
== Errors

Whenever an error response (status code >= 400) is returned, the body will contain a JSON object
that describes the problem. The error object has the following structure:

For example, a request that attempts to save a malformed superhero will produce a
`400 Bad Request` response:

[[overview-hypermedia]]
== Hypermedia

RESTful Notes uses hypermedia and resources include links to other resources in their
responses. Responses are in http://stateless.co/hal_specification.html[Hypertext Application
Language (HAL)] format. Links can be found benath the `_links` key. Users of the API should
not created URIs themselves, instead they should use the above-described links to navigate
from resource to resource.

[[resources]]
= Resources

[[resources-save-superhero]]
== Save (add or update) a superhero

=== Example
include::{snippets}/test-save-superhero/curl-request.adoc[]

=== HTTP request
include::{snippets}/test-save-superhero/http-request.adoc[]

=== HTTP response
include::{snippets}/test-save-superhero/http-response.adoc[]

=== Request fields
include::{snippets}/test-save-superhero/request-fields.adoc[]

[[resources-get-superhero]]
== Get a superhero

=== Example
include::{snippets}/test-get-superhero/curl-request.adoc[]

=== HTTP request
include::{snippets}/test-get-superhero/http-request.adoc[]

=== HTTP response
include::{snippets}/test-get-superhero/http-response.adoc[]

=== Response fields
include::{snippets}/test-get-superhero/response-fields.adoc[]

[[resources-find-superheros]]
== Find superheros

=== Example
include::{snippets}/test-find-superheros/curl-request.adoc[]

=== HTTP request
include::{snippets}/test-find-superheros/http-request.adoc[]

=== HTTP response
include::{snippets}/test-find-superheros/http-response.adoc[]

[[resources-delete-superhero]]
== Delete a superhero

=== Example
include::{snippets}/test-delete-superhero/curl-request.adoc[]

=== HTTP request
include::{snippets}/test-delete-superhero/http-request.adoc[]

=== HTTP response
include::{snippets}/test-delete-superhero/http-response.adoc[]

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

= Spring REST Docs API

luisalbertogh <luisalbertogh@hotmail.com>

:doctype: book

:toc:

:sectanchors:

:sectlinks:

:toclevels: 4

:source-highlighter: highlightjs

[[overview]]

= Overview

[[overview-http-verbs]]

== HTTP verbs

RESTful SpringRestDocs tries to adhere as closely as possible to standard HTTP and REST conventions in its

use of HTTP verbs.

|===

| Verb | Usage

| `GET`

| Used to retrieve a resource

| `POST`

| Used to create (add or update) a new resource

| `DELETE`

| Used to delete an existing resource

|===

[[overview-http-status-codes]]

== HTTP status codes

RESTful SpringRestDocs tries to adhere as closely as possible to standard HTTP and REST conventions in its

use of HTTP status codes.

|===

| Status code | Usage

| `200 OK`

| The request completed successfully

| `201 Created`

| A new resource has been saved (created or updated) successfully.

// The resource's URI is available from the response's `Location` header

| `302 Found`

| The searched resource was successfully found

| `400 Bad Request`

| The request was malformed. The response body will include an error providing further information

| `404 Not Found`

| The requested resource did not exist

|===

[[overview-errors]]

== Errors

Whenever an error response (status code >= 400) is returned, the body will contain a JSON object

that describes the problem. The error object has the following structure:

For example, a request that attempts to save a malformed superhero will produce a

`400 Bad Request` response:

[[overview-hypermedia]]

== Hypermedia

RESTful Notes uses hypermedia and resources include links to other resources in their

responses. Responses are in http://stateless.co/hal_specification.html[Hypertext Application

Language (HAL)] format. Links can be found benath the `_links` key. Users of the API should

not created URIs themselves, instead they should use the above-described links to navigate

from resource to resource.

[[resources]]

= Resources

[[resources-save-superhero]]

== Save (add or update) a superhero

=== Example

include::{snippets}/test-save-superhero/curl-request.adoc[]

=== HTTP request

include::{snippets}/test-save-superhero/http-request.adoc[]

=== HTTP response

include::{snippets}/test-save-superhero/http-response.adoc[]

=== Request fields

include::{snippets}/test-save-superhero/request-fields.adoc[]

[[resources-get-superhero]]

== Get a superhero

=== Example

include::{snippets}/test-get-superhero/curl-request.adoc[]

=== HTTP request

include::{snippets}/test-get-superhero/http-request.adoc[]

=== HTTP response

include::{snippets}/test-get-superhero/http-response.adoc[]

=== Response fields

include::{snippets}/test-get-superhero/response-fields.adoc[]

[[resources-find-superheros]]

== Find superheros

=== Example

include::{snippets}/test-find-superheros/curl-request.adoc[]

=== HTTP request

include::{snippets}/test-find-superheros/http-request.adoc[]

=== HTTP response

include::{snippets}/test-find-superheros/http-response.adoc[]

[[resources-delete-superhero]]

== Delete a superhero

=== Example

include::{snippets}/test-delete-superhero/curl-request.adoc[]

=== HTTP request

include::{snippets}/test-delete-superhero/http-request.adoc[]

=== HTTP response

include::{snippets}/test-delete-superhero/http-response.adoc[]

La ruta al fichero se incluye en el plugin de Asciidoctor para Maven, en el pom.xml.

<!-- Asciidoctor plugin - Plugin for REST documentation -->
      <plugin>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctor-maven-plugin</artifactId>
            <version>1.5.2</version>
            <executions>
                <execution>
                    <id>generate-docs</id>
                    <!-- Configured to include documentation within the executable JAR file -->
                    <phase>prepare-package</phase>
                    <goals>
                        <goal>process-asciidoc</goal>
                    </goals>
                    <configuration>
                        <strong><sourceDirectory>src/docs/asciidoc</sourceDirectory></strong>
                        <strong><outputDirectory>${project.build.directory}/generated-docs/${project.version}</outputDirectory></strong>
                        <backend>html</backend>
                        <doctype>book</doctype>
                        <attributes>
                            <snippets>${project.build.directory}/generated-snippets</snippets>
                        </attributes>
                    </configuration>
                </execution>
            </executions>
        </plugin>

<groupId>org.asciidoctor</groupId>

<artifactId>asciidoctor-maven-plugin</artifactId>

<id>generate-docs</id>

<phase>prepare-package</phase>

<goals>

<goal>process-asciidoc</goal>

</goals>

<sourceDirectory>src/docs/asciidoc</sourceDirectory>

<outputDirectory>${project.build.directory}/generated-docs/${project.version}</outputDirectory>

<snippets>${project.build.directory}/generated-snippets</snippets>

</attributes>

</configuration>

</execution>

</executions>

</plugin>

6. Ejecución de tests y generación de documentación

Configuramos los plugin de Maven en el pom.xml para que se ejecute la generación de la documentación al generar un nuevo “release” de la aplicación, es decir, cuando se invoque el goal “package” de Maven. Previamente se ejecutarán los tests de forma automática. Si falla el test o la generación de la documentación para un servicio dado, se indicará en la salida por consola y no se generará ni el release ni la documentación de ninguno de los servicios.

Maven goals

7. Visualización de la documentación generada

La documentación se genera en la ruta indicada en el plugin de Maven (ver arriba). Por un lado se generan los “snippets” que es la documentación que corresponde a cada servicio, y por otro una página principal o índice HTML que enlaza a esso “snippets” según hayamos indicado en el fichero de texto plano que define la página y que se describe en el punto 5.

Índice generado

Descripción de los servicios web

Spring Web Sockets con STOMP y SockJS (y Spring Boot)

Este nuevo post presenta un sencillo ejemplo del desarrollo de una aplicación web (lanzada e inicializada mediante Spring Boot) que hace uso de web sockets para establecer una comunicación bidireccional asíncrona entre el cliente (el navegador web) y el servidor (la aplicación ejecutada en el Tomcat embebido de Spring Boot).

Para ello usaremos:

- Spring Boot, para inicializar la aplicación, resolver las dependencias, ejecutarla en el Tomcat embebido, etc.

- Spring Web Sockets, para implementar la parte correspondiente a ellos.

- STOMP y SockJS para crear el cliente en JavaScript que se ejecutará desde una página web en el navegador y facilitar las comunicaciones via JSON.

El objetivo es desarrollar una aplicación web que:

- Conecte al servidor, estableciendo el canal de comunicación para recibir los mensajes desde el servidor.

- Envíe un mensaje al servidor y reciba una respuesta que mostrará por pantalla.

- Permanezca a la escucha de los mensajes que le lleguen desde el servidor y los imprima por pantalla.

- Finalice la conexión al servidor, cerrando el canal de comunicación establecido por los web sockets.

Los pasos a seguir serían los siguientes:

1. Inicialización de la aplicación con Spring Boot

Para conocer algo más sobre Spring Boot se puede consultar este otro post sobre el tema dentro del blog, o la documentación oficial. Basicamente lo que se pretende es usar Spring Boot para preparar una aplicación con todas las dependencias y configuraciones iniciales necesarias para desarrollar una aplicación web que soporte Spring Web Sockets. Usaremo Spring MVC y Spring Web Sockets para esto. Para ello creamos un proyecto Java en Eclipse, lo mavenizamos y añadimos las siguientes dependencias al pom.xml (podemos partir de la aplicación desarrollada en el post antes mencionado sobre Spring Boot):

<!-- Add typical dependencies for a web application -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-web</artifactId>
</dependency>

<!-- Dependencies for a web sockets -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-websocket</artifactId>
</dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-web</artifactId>

</dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-websocket</artifactId>

</dependency>

2. Creamos los DTOs que usaremos para transferir la información entre el cliente y el servidor y viceversa

La aplicación que vamos a desarrollar es una sencilla web que facilita información meteorológica en tiempo real. Contaremos con un sencillo formulario web que permite introducir el nombre de una ciudad. Se envía el nombre de la ciudad al servidor y se recibe la información meteorológica sobre esa ciudad en ese momento. Además cualquier cliente que este escuchando en ese momento en el mismo canal, recibirá la misma información. También se puede recibir la información meteorológica en tiempo real si se escucha en el web socket y esta se envía de forma periódica desde el servidor.

Por lo tanto, tenemos dos tipos de mensajes. El que envía el cliente al servidor con el nombre de la ciudad, y el que envía el servidor al cliente con la información meteorológica. Esta información se enviará en JSON pero dentro del servidor se implementará como un par de DTOs o POJOs o Java beans, es decir, como un par de clases sencillas con sus atributos y metodos de acceso (get/set).

/**
* @author lagarcia
*
*/
public final class PlaceInfo {
/** The place name. */
private String place;

/**
* @param placeArg
*/
public PlaceInfo() {
/* Empty */
}

/**
* @param placeArg
*/
public PlaceInfo(String placeArg) {
place = placeArg;
}

/**
* @return the place
*/
public String getPlace() {
return place;
}

/**
* @param placeArg
*            the place to set
*/
public void setPlace(String placeArg) {
place = placeArg;
}

}

/**
* @author lagarcia
*
*/
public final class WeatherInfo {
/** The weather type. */
private WeatherType type;
/** The local date and time. */
private LocalDateTime time;
/** The local date time as string. */
private String localDateTimeStr;
/** The place. */
private String place;

/**
* Defaul constructor.
*/
public WeatherInfo() {
/* Empty */
}

/**
* Constructor with args.
*
* @param typeArg
* @param timeArg
* @param placeArg
*/
public WeatherInfo(WeatherType typeArg, LocalDateTime timeArg,
String placeArg) {
super();
type = typeArg;
time = timeArg;
place = placeArg;
}

/**
* @return the type
*/
public WeatherType getType() {
return type;
}

/**
* @param typeArg
*            the type to set
*/
public void setType(WeatherType typeArg) {
type = typeArg;
}

/**
* @return the time
*/
public LocalDateTime getTime() {
return time;
}

/**
* @param timeArg
*            the time to set
*/
public void setTime(LocalDateTime timeArg) {
time = timeArg;
}

/**
* @return the place
*/
public String getPlace() {
return place;
}

/**
* @param placeArg
*            the place to set
*/
public void setPlace(String placeArg) {
place = placeArg;
}

/**
* @return the localDateTimeStr
*/
public String getLocalDateTimeStr() {
return time.format(DateTimeFormatter.ISO_LOCAL_DATE_TIME);
}

/**
* @param localDateTimeStrArg
*            the localDateTimeStr to set
*/
public void setLocalDateTimeStr(String localDateTimeStrArg) {
localDateTimeStr = localDateTimeStrArg;
}
}

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

/**

* @author lagarcia

public final class PlaceInfo {

/** The place name. */

private String place;

/**

* @param placeArg

public PlaceInfo() {

/* Empty */

}

/**

* @param placeArg

public PlaceInfo(String placeArg) {

place = placeArg;

}

/**

* @return the place

public String getPlace() {

return place;

}

/**

* @param placeArg

* the place to set

public void setPlace(String placeArg) {

place = placeArg;

}

/**

* @author lagarcia

public final class WeatherInfo {

/** The weather type. */

private WeatherType type;

/** The local date and time. */

private LocalDateTime time;

/** The local date time as string. */

private String localDateTimeStr;

/** The place. */

private String place;

/**

* Defaul constructor.

public WeatherInfo() {

/* Empty */

}

/**

* Constructor with args.

* @param typeArg

* @param timeArg

* @param placeArg

public WeatherInfo(WeatherType typeArg, LocalDateTime timeArg,

String placeArg) {

super();

type = typeArg;

time = timeArg;

place = placeArg;

}

/**

* @return the type

public WeatherType getType() {

return type;

}

/**

* @param typeArg

* the type to set

public void setType(WeatherType typeArg) {

type = typeArg;

}

/**

* @return the time

public LocalDateTime getTime() {

return time;

}

/**

* @param timeArg

* the time to set

public void setTime(LocalDateTime timeArg) {

time = timeArg;

}

/**

* @return the place

public String getPlace() {

return place;

}

/**

* @param placeArg

* the place to set

public void setPlace(String placeArg) {

place = placeArg;

}

/**

* @return the localDateTimeStr

public String getLocalDateTimeStr() {

return time.format(DateTimeFormatter.ISO_LOCAL_DATE_TIME);

}

/**

* @param localDateTimeStrArg

* the localDateTimeStr to set

public void setLocalDateTimeStr(String localDateTimeStrArg) {

localDateTimeStr = localDateTimeStrArg;

}

Como no tenemos capa de persistencia ni acceso a base de datos o similar, crearemos un mapa con datos en memoria (WeatherData.java) donde insertaremos unos cuantos DTOs con información meteorológica de tres lozalizaciones, con datos como el tipo de tiempo, la hora en formato ISO o el lugar. 3. Configuración de los Web Sockets La configuración de los web sockets se hace en este caso como casi todo en Spring Boot, mediante una clase java y usando anotaciones.

@Configuration
@EnableWebSocketMessageBroker
public class WebSocketConfig extends AbstractWebSocketMessageBrokerConfigurer {
    @Override
    public void configureMessageBroker(MessageBrokerRegistry config) {
        config.enableSimpleBroker("/topic");
        config.setApplicationDestinationPrefixes("/app");
    }

    @Override
    public void registerStompEndpoints(StompEndpointRegistry registry) {
        registry.addEndpoint("/weather").withSockJS();
    }
}

@Configuration

@EnableWebSocketMessageBroker

public class WebSocketConfig extends AbstractWebSocketMessageBrokerConfigurer {

@Override

public void configureMessageBroker(MessageBrokerRegistry config) {

config.enableSimpleBroker("/topic");

config.setApplicationDestinationPrefixes("/app");

}

@Override

public void registerStompEndpoints(StompEndpointRegistry registry) {

registry.addEndpoint("/weather").withSockJS();

}

En este caso, indicamos con @Configuration que es una clase de configuración de Spring (lo que eran antes los antiguos XML). Ademas con @EnableWebSocketMessageBroker indicamos que vamos a configurar los web sockets. En el primer método establecemos el mecanismo (broker) que escribira en el canal de mensajes del servidor a los clientes y cuya URI (del canal) empezará por “/topic”. En este caso es un broker sencillo que solo mantiene sus mensajes en memoria (sin persistencia). También indicamos que los mensajes de los clientes al servidor irán dirigidos a una URL que empezará por “/app”. En el segundo método se establece “/weather” como la URI del web socket creado y se indica que se espera SockJS para establecer la comunicación desde el cliente.

4. El controlador (y los posibles servicios)

Esta parte comprende la implementación del web socket en sí. En este caso vamos a usar un @Controller de Spring MVC para desarrollar un servicio que recibe el mensaje desde el cliente y responde desde el servidor usando el web socket antes configurado.

También se puede desarrollar un servicio, bien a nivel de controlador web, o bien a nivel de servicio, que escriba directamente en el web socket desde el servidor. El cliente que este escuchando en el canal recibirá el mensaje igualmente.

@Controller
@EnableScheduling
public final class WeatherController {

/** A logger reference */
private static Logger logger = Logger.getLogger(WeatherController.class);

/** The data storage. */
@Autowired
private WeatherData wData;

/** Web socket message template */
@Autowired
private SimpMessagingTemplate template;

/**
* Get weather info for a given place.
*
* @param place
*            - The place
* @return The weather info
*/
@MessageMapping("/weather")
@SendTo("/topic/weatherinfo")
public WeatherInfo getWeatherInfo(PlaceInfo place) {
/* Default */
WeatherInfo wInfo = new WeatherInfo();
try {
logger.info("Get weather from " + place.getPlace());

/* Lets make a pause */
Thread.sleep(1000);

/* Return weather info for the given place */
wInfo = wData.getWeatherFrom(place.getPlace());

logger.info("Retrieving weather from " + place.getPlace());

} catch (Exception ex) {
ex.printStackTrace();
}

return wInfo;
}

/**
* Run weather info periodically.
*/
// @Scheduled(fixedRate = 2000)
public void runWInfo() {
this.template.convertAndSend("/topic/weatherinfo",
wData.getWeatherFrom("Madrid"));
}

/**
* @return the wData
*/
public WeatherData getwData() {
return wData;
}

/**
* @param wDataArg
*            the wData to set
*/
public void setwData(WeatherData wDataArg) {
wData = wDataArg;
}
}

@Controller

@EnableScheduling

public final class WeatherController {

/** A logger reference */

private static Logger logger = Logger.getLogger(WeatherController.class);

/** The data storage. */

@Autowired

private WeatherData wData;

/** Web socket message template */

@Autowired

private SimpMessagingTemplate template;

/**

* Get weather info for a given place.

* @param place

* - The place

* @return The weather info

@MessageMapping("/weather")

@SendTo("/topic/weatherinfo")

public WeatherInfo getWeatherInfo(PlaceInfo place) {

/* Default */

WeatherInfo wInfo = new WeatherInfo();

try {

logger.info("Get weather from " + place.getPlace());

/* Lets make a pause */

Thread.sleep(1000);

/* Return weather info for the given place */

wInfo = wData.getWeatherFrom(place.getPlace());

logger.info("Retrieving weather from " + place.getPlace());

} catch (Exception ex) {

ex.printStackTrace();

}

return wInfo;

}

/**

* Run weather info periodically.

// @Scheduled(fixedRate = 2000)

public void runWInfo() {

this.template.convertAndSend("/topic/weatherinfo",

wData.getWeatherFrom("Madrid"));

}

/**

* @return the wData

public WeatherData getwData() {

return wData;

}

/**

* @param wDataArg

* the wData to set

public void setwData(WeatherData wDataArg) {

wData = wDataArg;

}

Las anotaciones que aplican a los Web Sockets son @MessageMapping(“/weather”) y @SendTo(“/topic/weatherinfo”). La primera indica que la URL a la que hay que invocar para enviar el mensaje al web socket es “/weather”. Entonces el JSON enviado se parseará automaticamente al DTO que es el argumento del método, como en un servicio web o un método de Spring MVC. La segunda anotación indica que la respuesta del método se enviará automaticamente a “/topic/weatherinfo”. Esa sería la URL del canal de respuestas desde el servidor en el que tendría que escuchar el cliente para recibir las respuestas.

Tenemos por lo tanto un método (o servicio) que recibe mensajes de los cliente y los contesta usando el web socket (getWeatherInfo). Pero además tenemos un método (runWInfo) que escribe directamente en el web socket sin más (si se descomenta la anotacion de @Scheduled se ejecutará cada 2 segundos). Para ello hace uso del SimpMessagingTemplate, indica la URL del web socket a escribir y el mensaje a enviar (el DTO).

Resumiendo:

- Hemos configurado un web socket “llamado” “/weather” (ver punto 3).

- Los clientes escriben al web socket si envían un mensaje a “/app/weather” (ver punto 3).

- El servidor escribe al web socket si envía un mensaje a “/topic/weatherinfo” (ver punto 3 y 4).

- Se puede usar el web socket para recibir del cliente y enviar desde el servidor (como en un servicio web o peticion HTTP estandar) o solo para enviar desde el servidor.

5. El cliente de JavaScript

El cliente es una página HTML muy sencilla que hace uso de las siguientes funciones de JavaScript:

/* JavaScript for websocket client */
var stompClient = null;

/* Show connection status */
function setConnected(connected) {
var status = "disconnected";
if(connected){
status = "connected";
}
document.getElementById('status').innerHTML = status;
}

/* Connect to topic using web sockets */
function connect() {
var socket = new SockJS('/weather');
stompClient = Stomp.over(socket);
stompClient.connect({}, function(frame) {
setConnected(true);
console.log('Connected: ' + frame);
stompClient.subscribe('/topic/weatherinfo', function(weather){
showWeather(JSON.parse(weather.body));
});
});
}

/* Disconnect */
function disconnect() {
if (stompClient != null) {
stompClient.disconnect();
}
setConnected(false);
console.log("Disconnected");
}

/* Send place */
function sendPlace() {
var name = document.getElementById('place').value;
stompClient.send("/app/weather", {}, JSON.stringify({ 'place': name }));
}

/* Show weather info */
function showWeather(wInfo) {
var response = document.getElementById('weatherInfo');
var newInfo = "<p>[" + wInfo.localDateTimeStr + "](" + wInfo.place + "): " + wInfo.type + "</p>"
var content = response.innerHTML;
response.innerHTML = content + newInfo;
}

/* JavaScript for websocket client */

var stompClient = null;

/* Show connection status */

function setConnected(connected) {

var status = "disconnected";

if(connected){

status = "connected";

}

document.getElementById('status').innerHTML = status;

}

/* Connect to topic using web sockets */

function connect() {

var socket = new SockJS('/weather');

stompClient = Stomp.over(socket);

stompClient.connect({}, function(frame) {

setConnected(true);

console.log('Connected: ' + frame);

stompClient.subscribe('/topic/weatherinfo', function(weather){

showWeather(JSON.parse(weather.body));

});

}

/* Disconnect */

function disconnect() {

if (stompClient != null) {

stompClient.disconnect();

}

setConnected(false);

console.log("Disconnected");

}

/* Send place */

function sendPlace() {

var name = document.getElementById('place').value;

stompClient.send("/app/weather", {}, JSON.stringify({ 'place': name }));

}

/* Show weather info */

function showWeather(wInfo) {

var response = document.getElementById('weatherInfo');

var newInfo = "[" + wInfo.localDateTimeStr + "](" + wInfo.place + "): " + wInfo.type + ""

var content = response.innerHTML;

response.innerHTML = content + newInfo;

}

A su vez estas funciones hacen uso de las librerias stomp.js y sockjs.js. El objetivo es implementar un cliente en JavaScript que:

a. Establezca la conexión con el web socket del servidor.

b. Envie mensajes por el web socket.

c. Escuche todos los mensajes que le lleguen por el web socket y los muestre por pantalla.

Para ello primero ha de conectar. Al conectar, se suscribe al canal del web socket, es decir, ya lo puede usar para enviar y recibir. Despues puede enviar o simplemente permanecer a la escucha. En el momento en el que lea algo del canal, lo procesará. Esto es lo que hace los metodos antes expuestos. El método connect establece la conexión con el web socket “/weather” y suscribe el cliente al canal de escucha “/topic/weatherinfo” que es donde escribe el servidor. En el momento en que recibe algo, lo pasa al método showWeather para que lo procese como un JSON. El método sendPlace() escribe un JSON a la URL “/app/weather”, que como establecimos en la configuración, es la URL en la que el servidor recibirá los mensajes del cliente.

6. El ejemplo

Este sería el aspecto del ejemplo. En un primer momento aparece como desconectado:

Desconectado

Pulsando en el boton de “Connect” establecemos la conexión entre el cliente y el servidor a través del web socket.

Conectado

Ahora podemos simplemente esperar a que el servidor nos envie algo, o podemos preguntar nosotros, usando el campo y el boton de “Send place”. Si ponemos “Madrid” y pulsamos…

Envio/Respuesta

Para apreciar la potencia de la comunicación via web sockets, si abrimos otro navegador y vamos a la misma página, recibiremos también el mismo mensaje del servidor aunque no hayamos preguntado. Si estamos conectados estamos escuchando al mismo canal de comunicación y recibiendo los mismos mensajes que el resto de los clientes. Un ejemplo práctico de esto podría ser un chat o cualquier aplicación en tiempo real.

Modo chat

Se puede descargar el proyecto para Eclipse a modo de ejemplo de este enlace. Y el código fuente desde Github. Más información sobre Spring Web Sockets desde la web oficial.

Iniciándose con Spring Boot (I)

Comenzamos una serie de posts sobre una tecnología de Spring muy interesante, llamada Spring Boot.

Spring Boot es una parte de Spring que nos permite crear diferentes tipos de aplicaciones de una manera rápida y sencilla. Sus características principales son que provee out-of-the-box una serie de elementos que nos permiten desarrollar diferentes tipos de aplicaciones de forma casi inmediata. Algunas de estas características son:

Servidores de aplicaciones embebidos (Tomcat, Jetty, Undertow)
POMs con dependencias y plug-ins para Maven
Uso extensivo de anotaciones que realizan funciones de configuración, inyección, etc.

Un ejemplo práctico del inicio de un desarrollo con Spring Boot puede ser el siguiente. A continuación crearemos un proyecto en Eclipse, lo configuraremos para usar Spring Boot y crearemos una primera aplicación web haciendo uso del Tomcat embebido que trae Spring Boot.

1. Creamos un proyecto Java en Eclipse

Creamos un proyecto Java estandar en Eclipse. En este caso estamos usando Eclipse Luna. Creamos un proyecto Java. Añadimos un directorio ‘java’ dentro de ‘src’ y establecemos la ruta ‘src/java’ como ruta de las fuentes dentro del classpath del proyecto. Esto no es necesario para Spring Boot, simplemente sirve para dar una estructura coherente al proyecto.

Proyecto en Eclipse

2. Mavenizamos el proyecto

Activamos las opciones de Maven para el proyecto para poder usar el pom a la hora de resolver dependencias, usar plug-ins, etc. Esto si es recomendable a la hora de usar Spring Boot ya que aunque podemos descargar los JAR necesarios, a la hora de usarlos y resolver otras dependencias, o generar diferentes distribuibles, será beneficioso disponer de Maven.

Al mavenizar el proyecto, se crea de forma automática el pom.xml del proyecto. Agregamos al POM lo siguiente:

Para que se añadan las dependencias necesarias para Spring Boot, plug-ins, etc, heredamos del POM de Spring Boot tal que asi:

<parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>1.3.0.BUILD-SNAPSHOT</version>
</parent>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-parent</artifactId>

<version>1.3.0.BUILD-SNAPSHOT</version>

</parent>

En este caso, como vamos a desarrollar aplicaciones web, entre otras, añadimos la siguiente dependencia también:

<!-- Add typical dependencies for a web application -->
<dependencies>
  <!-- Import dependency management from Spring Boot (if parent POM not downloaded) -->
  <!-- <dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-dependencies</artifactId>
   <version>1.3.0.BUILD-SNAPSHOT</version>
   <type>pom</type>
   <scope>import</scope>
  </dependency> -->

  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>
</dependencies>

<!-- <dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-dependencies</artifactId>

<version>1.3.0.BUILD-SNAPSHOT</version>

<scope>import</scope>

</dependency> -->

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-web</artifactId>

</dependency>

</dependencies>

Añadimos el siguiente plug-in para crear los JAR como ficheros ejecutables:

<!-- Package as an executable jar -->
<plugin>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-maven-plugin</artifactId>
</plugin>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-maven-plugin</artifactId>

</plugin>

Por último, en caso de no disponer de una versión completa de Spring, agregamos la configuración de los siguientes repositorios en caso de tener que descargar las correspondientes dependencias:

<!-- Add Spring repositories -->
<!-- (you don't need this if you are using a .RELEASE version) -->
<repositories>
  <repository>
    <id>spring-snapshots</id>
    <url>http://repo.spring.io/snapshot</url>
    <snapshots><enabled>true</enabled></snapshots>
  </repository>
  <repository>
    <id>spring-milestones</id>
    <url>http://repo.spring.io/milestone</url>
  </repository>
</repositories>
<pluginRepositories>
  <pluginRepository>
    <id>spring-snapshots</id>
    <url>http://repo.spring.io/snapshot</url>
  </pluginRepository>
  <pluginRepository>
    <id>spring-milestones</id>
    <url>http://repo.spring.io/milestone</url>
  </pluginRepository>
</pluginRepositories>

<id>spring-snapshots</id>

<url>http://repo.spring.io/snapshot</url>

</repository>

<id>spring-milestones</id>

<url>http://repo.spring.io/milestone</url>

</repository>

</repositories>

<id>spring-snapshots</id>

<url>http://repo.spring.io/snapshot</url>

</pluginRepository>

<id>spring-milestones</id>

<url>http://repo.spring.io/milestone</url>

</pluginRepository>

</pluginRepositories>

El pom.xml final podria quedar tal que asi.

Ejecución en Maven

3. Implementamos la aplicación

Como ejemplo práctico de inicio, podemos codificar la siguiente clase:

package net.luisalbertogh.springboot.controllers;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
* Example controller class.
* @author lagarcia
*
*/
@RestController
@EnableAutoConfiguration
public class ExampleController {

  /**
  * Go to home.
  * @return
  */
  @RequestMapping("/")
  String home(){
    return "Hola Spring Boot";
  }

  /**
  * Main method.
  * @param args
  */
  public static void main(String[] args) {
    SpringApplication.run(ExampleController.class, args);
  }
}

package net.luisalbertogh.springboot.controllers;

import org.springframework.boot.SpringApplication;

import org.springframework.boot.autoconfigure.EnableAutoConfiguration;

import org.springframework.web.bind.annotation.RequestMapping;

import org.springframework.web.bind.annotation.RestController;

/**

* Example controller class.

* @author lagarcia

@RestController

@EnableAutoConfiguration

public class ExampleController {

/**

* Go to home.

* @return

@RequestMapping("/")

String home(){

return "Hola Spring Boot";

}

/**

* Main method.

* @param args

public static void main(String[] args) {

SpringApplication.run(ExampleController.class, args);

}

Esta clase implementa un controlador web. Usa, ademas de Spring Boot, caracterísiticas de Spring MVC para ello. Las anotaciones presentes configuran la clase como controlador y establecen un mapeado entre el ‘/’ y una funcionalidad específica (devuelve un texto). La anotación @EnableAutoConfiguration configura la aplicación sin necesidad de otros ficheros de configuración XML, etc. Por último, se ejecuta el aplicativo usando la clase SpringApplication de Spring Boot.

4. Modificar las propiedades

El Tomcat embebido se lanza en el puerto 8080 por defecto. Como tenemos ese puerto ocupado, lo podemos cambiar usando diferentes mecanismos de propiedades del entorno de Spring Boot. Una de las formas de cambiar estas propiedades es usando el fichero application.properties. Spring Boot cargará automaticamente las propiedades que encuentre en el fichero application.properties si lo encuentra en una de las posibles localizaciones. Una de esas localizaciones es el directorio ‘config/’ dentro del directorio raíz del proyecto. Para más información acerca de la configuración de Spring Boot se puede consultar este enlace.

De esta manera, cambiamos el puerto de Tomcat al 9999:

# Spring Boot application properties

# Tomcat port
server.port=9999

# Spring Boot application properties

# Tomcat port

server.port=9999

Proyecto en Eclipse completo

5. Lanzar la aplicación

Finalmente solo nos queda compilar y lanzar la aplicación via Maven. Para ello podemos crear desde Eclipse un modo de ejecución via Maven con el plug-im m2 correspondiente. Lanzamos el goal ‘spring-boot:run’. Esto compila los cambios, ejecuta los posibles tests y lanza el aplicativo. En este caso, arranca el Tomcat embebido y ya tenemos la aplicación disponible en la siguiente URL:

http:\\localhost:9999

Ejecución desde Eclipse

Spring Boot web app

El Recetario

Recetas Java y más

Category Archives: Web

Testeando y documentando REST WS con Spring REST Docs

Qué cocinamos

Ingredientes

Paso a paso

1. Desarrollar la aplicación de prueba que implementa los servicios web

2. POJO y DAO

3. Servicios web

4. Tests de servicios y generación de documentación

5. Asciidoctor

6. Ejecución de tests y generación de documentación

7. Visualización de la documentación generada

Spring Web Sockets con STOMP y SockJS (y Spring Boot)

Iniciándose con Spring Boot (I)