Documentando APIs en Spring: Swagger

Documentar nuestras APIs es fundamental para que nuestro servicio pueda ser utilizado de forma sencilla y rápida. Generalmente se documentan las operaciones disponibles con sus parámetros de entrada, y las posibles salidas. Documentar es una tarea compleja porque debemos hacerlo cada vez que modificamos el código. Por eso es imprescindible el uso de herramientas que reduzcan esta complejidad.

Una de las especificaciones más extendidas para la documentación es la conocida como OpenAPI, que permite describir nuestra documentación mediante JSON o YAML. Con OpenAPI podemos especificar endpoints disponibles, operaciones y sus parametros, métodos de autenticación y información de contacto.

Swagger es una de las herramientas más utilizadas que implementan la especificación OpenAPI. Y SpringFox is la integración de Swagger para el framework Spring. Los componentes de Swagger son:
  • Swagger Editor – Un editor web en el que se pueden escribir especificaciones OpenAPI.
  • Swagger UI – Una aplicación web que genera una API interactiva.
  • Swagger Codegen – Una herramienta que genera librerías para OpenAPI.
Dependencias necesarias
Y para configurar Swagger necesitas crear un Docket Bean:
Toda la información necesaria está muy bien explicada en la documentación oficial

Comentarios

Publicar un comentario

Entradas populares de este blog

Django REST framework

Imagen
Django REST framework es el framework por excelencia si queremos crear una API RESTful en Django. Proporciona todo lo necesario para su implementación de una manera completa y eficaz. Lista de virtudes: Autenticación Validación de datos Excepciones en JSON Soporte para relaciones Paginación y filtros Para instalarlo: Respuestas Antes de comenzar vamos a ver la implementación de los dos tipos de respuesta comunes que una API suele ofrecer: 1. Repsuesta JSON : Por defecto, y por seguridad, JsonResponse sólo permite el uso de diccionarios. Si queremos devolver otra cosa podemos saltarnos esta seguridad incluyendo el parametro safe a False. 2. Repsuesta HTTP : Generalmente usado como respuestas vacias con códigos de estado HTTP. Por ejemplo, el código 204 significa No Content. Esto indica que la petición fue aceptada pero que no se devuelve datos. Usamos esta tipo de respuesta cuando un recurso es actualizado (PUT) o borrado (DELETE). El otro código más po
Leer más

Envío de checkboxes o selector multiple por AJAX con jQuery

Pasar parámetros de un formulario mediante las llamadas ajax que proporciona jQuery resulta realmente sencillo. Pero ¿qué pasa si queremos enviar un conjunto de checkboxes? ¿y si queremos enviar varias opciones seleccionadas de un selector múltiple? Pues la solución es igual de sencilla: Serializar. Con una pequeña función podemos serializar estos datos para enviarlos todos juntos como parametro. Aquí podéis ver el código:
Leer más

Django: relaciones polimórficas

Imagen
Django tiene varias formas de relacionar modelos entre sí: ForeingKey ManyToManyField OneToManyField Una de las limitaciones de este sistema es que esta relación es estática, solo permite la relación a un tipo de modelo. No permite relaciones polimórficas. Si conoces PHP y el framework Laravel, sabrás a que me refiero. Sin embargo, Django incluye una aplicación llamada "contenttypes" que además de permirte seguir todos los modelos instalados en tu proyecto y un interfaz para trabajar con ellos, permite generar estas relaciones polimórficas llamadas "relaciones genéricas". Ejemplo de relación genérica: Este modelo Comment está referenciando al Post en el que se incluye. ForeingKey es la relación adecuada ya que un comentario sólo pertenece a un post. Pero si quisieramos utilizar este modelo para hacer comentarios sobre otros elemntos que no fueran posts, tendríamos un problema, ya que está asociado directamente a un post. Solución: relaciones gen
Leer más