JsonDoc: generando documentación de nuestras APIS RESTful

Gracias a Diego y a su equipo hace unos días conocía este interesante framework para documentar nuestra APIS REST.

JSONDoc ofrece las principales funcionalidades de soluciones como Swagger (ver qué ofrece Swagger) y aunque no ofrece tantas utilidades como este sí que ofrece algunas ventajas sobre este, como la de estar codificado en Java y ser más simple (verdad Javier :D)

Concretamente, con JSONDoc podemos documentar un API RESTFul Java mediante anotaciones y exponer dicha documentación en el propio proyecto web mediante una página JSP que además nos permite testear los métodos del API a través de un cliente REST.

El API de JSONDoc nos da una serie de anotaciones con las que decorar la interfaz de nuestro API RESTFul, así como los objetos DTO que utilice:

De manera que posteriormente podremos visualizar la documentación en una interfaz web dentro de nuestro proyecto:

La interfaz web de documentación está compuesta por un menú donde seleccionar cada una de las APIs documentadas, asi como los DTOs de que hacen uso las APIS (sección OBJECTS).

En esta interfaz cada método del API es un desplegable que muestra toda su información, y proporciona un cliente REST desde el que se poder invocarlo pasando los parámetros que tenga:

JsonDOC está desarrollado siguiendo un modelo MVC y se estructura en 3 proyectos separados:

· jsondoc-core: Incluye el conjunto de anotaciones de JsonDoc

· jsondoc-springmvc: Incluye un controlador Spring MVC para generar la documentación del API en formato json y enviarla a la vista.

· jsondoc-ui: Incluye una página JSP que convierte la documentación json generada en el controlador a interfaz HTML.

De este modo, es posible incluirlo en nuestro proyecto, aunque no se trate de un proyecto SpringMVC y/o desarrollar nuestra propia pantalla de presentación.

Para añadir JsonDoc a nuestro proyecto hay que seguir los siguientes pasos:

1. Descargar las librerías de JsonDoc que vayamos a usar (Al menos es necesario Jsondoc-core.jar) e instalarlas en nuestro Maven Repo:

Ayuda: instalación manual de librerias en maven repo

mvn install:install-file -Dfile=[path-to-file] -DgroupId=[group-id] -DartifactId=[artifact-id] -Dversion=[version] -Dpackaging=[packaging]

Por lo que para instalar las libreria jsondoc-core y jsondoc-springmvc:

mvn install:install-file -Dfile=jsondoc-core.jar -DgroupId=org.jsondoc -DartifactId=jsondoc-core -Dversion=1.0.2 -Dpackaging=jar

mvn install:install-file -Dfile=jsondoc-springmvc.jar -DgroupId=org.jsondoc -DartifactId=jsondoc-springmvc -Dversion=1.0.2 -Dpackaging=jar

2. Añadir la dependencia de jsondoc-core a nuestro proyecto. Con esto tendremos disponible el juego completo de anotaciones para documentar nuestra API RESTFul

<dependency>

<groupId>org.jsondoc</groupId>

<artifactId>jsondoc-core</artifactId>

<version>1.0.2</version>

</dependency>

a) Si nuestro proyecto es Spring MVC, añadir también la dependencia de jsondoc-springmvc. Con esto añadimos un controlador Spring MVC que invoca a la utilidad del core que escanea las anotaciones de las APIs documentadas y devuelve la información en formato json

<dependency>
<groupId>org.jsondoc</groupId>
<artifactId>jsondoc-springmvc</artifactId>
<version>1.0.2</version>
</dependency>

En este caso, hay que declarar en nuestro application-context.xml el bean del controlador de jsondoc-springmvc:

<beanid="documentationController"class="org.jsondoc.springmvc.controller.JSONDocController">
<propertyname="version"value="1.0"/>
<propertyname="basePath"value="http://localhost:8080/api"/>
<propertyname="packages">
<list>
<value>com.mycompany.controller</value><!-- put here packages in which you have your spring controllers -->
<value>com.mycompany.pojo</value><!-- put here packages in which you have your objects -->
<value>org.external.stuff</value><!-- they can also belong to external jars: provide here their package -->
</list>
</property>
</bean>

Donde las propiedades son:

· version: Versión con que se documenta el API. Pej: 1.0

· basePath: Path base (url) en la que se exponen los servicios REST. Pej: http://localhost:8080/<modulo>/services

· packages: Lista de paquetes donde debe escanear para localizar APIs documentadas.

b) En caso de que nuestro proyecto NO sea Spring MVC que prefiramos desarrollar nuestro propio controlador, el modo obtener la información de las anotaciones de JsonDoc en nuestras APIs, es invocar a la utilidad del core:

JSONDocUtils.getApiDoc(version, basePath, packages);

Donde sus parámetros son los mismos que se informarían en el application-context.xml para el caso de que el controlador fuera un bean Spring MVC.

3. Añadir al proyecto la página JSP “jsondoc.jsp” que encontramos en jsondoc-ui. Esta JSP explota la información de las APIs devuelta en formato json desde el controlador, mostrando la documentación asociada a cada método, así como proporcinando un cliente REST desde el que invocarlos.

Nota: Por defecto, este JSP invoca al controlador mapeado en la url /jsondoc (Por defecto la que utilizar el controlador de JsonDoc-springmvc). En caso de desarrollar un controlador a medida que tuviese que mapear otra url, habria que indicarlo en el JSP en el atributo value del campo:

<input id=«jsondocfetch» class=«span5» type=«hidden» value=«jsondoc» />

Una incorporado JsonDoc a nuestro proyecto, lo siguiente es anotar nuestras APIs para documentarlas.

1. Describir globalmente el API:

· Anotación @Api aplicada a nivel de clase describiendo el API:

Esto añade una entrada al menú de APIs en la UI:

2. Describir cada uno de los métodos:

· Anotacion @ApiMethod describiendo el método

· Anotaciones @ApiErrors y @ApiError describiendo códigos de error manejados por el método

· Anotaciones @ApiResponseObject, @ApiBodyObject indicando DTOs de la petición y respuesta

· Anotacion @ApiParam describiendo parámetros de entrada tanto de tipo Path como de tipo Query

Esto añade el método al API en la UI, y prepara el cliente REST para poder invocarlo con los argumentos que recibe:

3. Describir los objetos DTO que utiliza el API:

· Anotación @ApiObject a nivel de clase describiendo el objeto

· Anotación @ApiObjectField describiendo cada atributo

Esto añade el DTO a la lista de objetos en el menú de la UI y permite su visualización:

Deja una respuesta

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Salir /  Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Salir /  Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Salir /  Cambiar )

Conectando a %s