Documentación Spring REST Docs

Introducción

Las aplicaciones se abren e interconectan cada vez más. Exponen y comparten sus estados a través de interfaces que, hoy en día, a menudo tienen forma de API REST con microservicios. Estas interfaces deben estar documentadas para facilitar el acceso a nuestras aplicaciones.

La documentación de las API públicas de LinkedIn, Facebook, Twitter, Google está particularmente bien hecha y algunas veces se compara con la documentación de nuestras API internamente, lo que nos impulsa a dedicar una cantidad considerable de tiempo para mantener la documentación clara, precisa y actualizada.

Para responder a esta necesidad, Spring ofrece una librería Spring REST Docs que se puede utilizar para crear documentación automática para los servicios REST. Esta posibilidad complementa a herramientas como Swagger (estática y dinámica) con SpringFox y el HAL Browser que, por ejemplo, muestran cómo funcionan los servicios.

La librería se basa en Asciidoctor y extractos de documentación para generar automáticamente, durante la compilación, texto plano o HTML.

También es posible generar Markdown (archivo *.md), que es muy práctico para usar en GitLab o GitHub, por ejemplo. La librería se utiliza junto con librerías de pruebas como jUnit y TestNG. La librería utiliza las pruebas para generar la documentación de extracción para las consultas y respuestas. Documenta las API basándose en la ejecución de pruebas, lo que garantiza que la API esté actualizada y que los ejemplos que muestra funcionen.

La documentación se centra en los recursos del servicio REST y detalla, por un lado, las consultas HTTP que consume la API y, por otro lado, las respuestas que produce, manteniendo oculta la parte de implementación.

En las siguientes secciones usaremos Maven, pero también es posible hacer el equivalente con Gradle. Del mismo modo, solo veremos parcialmente la documentación generada, ya que es muy completa. El ejemplo del capítulo permite ver rápidamente la documentación generada.

La librería de generación de documentos se inyecta en las pruebas. Podemos obtener resultados significativamente diferentes en función de las librerías de pruebas...

Ejemplo JUnit 5 (Jupiter)

La documentación del ejemplo se genera en el directorio target/generated-snippets. Sería posible especificar otro directorio.

Código de mockMvc

El mock es el que utiliza Spring REST Docs para generar la documentación. Es relativamente complejo. Lo ideal es usar el ejemplo que está disponible para su descarga y seguir las instrucciones.

private MockMvc mockMvc; 
 
@ExtendWith(RestDocumentationExtension.class) 
  public class JUnit5ExampleTests { 
 
  private MockMvc mockMvc; 
 
  @BeforeEach 
  public void setUp(WebApplicationContext webApplicationContext, 
  RestDocumentationContextProvider restDocumentation) { 
    this.mockMvc = 
       MockMvcBuilders.webAppContextSetup(webApplicationContext) 
         .apply(documentationConfiguration(restDocumentation)) 
         .build(); 
} 

Llamada de servicio:

this.mockMvc.perform(get("/").accept(MediaType.APPLICATION_JSON)) 
  .andExpect(status().isOk()) 
  .andDo(document("index")); 

Durante las builds, la herramienta genera extractos que son plantillas reutilizables. A continuación, podemos personalizar estos extractos:

Respuesta con JSON anidado

Podemos tener una respuesta con un JSON anidado.

Para una descripción como esta:

{ 
  "weather": { + 
    "wind": { + 
    "speed": 15.3, + 
    "direction": 287.0 + 
   }, 
  "temperature": { 
    "high": 21.2, 
    "low": 14.8 
    } 
  } 
} 

Podemos tener este código:

this.mockMvc.perform(get("/locations/1").accept(MediaType. 
APPLICATION_JSON)) + 
.andExpect(status().isOk()).andDo(document("location", + 
responseBody(beneathPath("weather.temperature")))); 
 
Identificador : beneath-$\{path}. 
 
Snippet : response-description-beneath-weather.temperature.adoc 

Código:

responseBody(beneathPath("weather.temperature") 
.withSubsectionId("temp")); 

Documentación de los campos:

this.mockMvc.perform(get("/locations/1").accept(MediaType. 
APPLICATION_JSON)) + 
.andExpect(status().isOk()) + 
.andDo(document("location", + 
responseFields(beneathPath("weather.temperature"), + 
fieldWithPath("high").description( + 
"The forecast high in degrees celcius"), + 
fieldWithPath("low") + 
.description("The forecast low in degrees celcius")))); 

Acoplamiento Swagger 2

Vimos que la documentación estática era necesaria y fácil de hacer con Spring y que podíamos usar el navegador HAL para exponer las API. También es posible utilizar Swagger 2. Esta sección describe dos usos de Swagger 2 en proyectos de Spring: uso estándar con Swagger 2 y un uso más avanzado con SpringFox.

Swagger permite una generación estática en tiempo de compilación y SpringFox permite una generación dinámica en tiempo de ejecución. Algunas veces usamos ambos juntos.

<dependency> 
 <groupId>io.springfox</groupId> 
 <artifactId>springfox-swagger2</artifactId> 
 <version>3.0.0</version> 
</dependency> 
<dependency> 
 <groupId>io.springfox</groupId> 
 <artifactId>springfox-swagger-ui</artifactId> 
 <version>3.0.0</version> 
</dependency> 

@Configuration ...