En este rápido tutorial vamos a mostrarte cómo documentar tu API de Sanidad en Nubentos. Vas a ver lo fácil y versátil que es ofrecer a los nuevos consumidores de tu API una documentación completa y ordenada.

Asociar una correcta documentación a tu API para Sanidad, permite a la comunidad de desarrolladores entender qué funcionalidades proporciona. Además, es uno de los aspectos clave para diferenciarse de la competencia y hacer tu API más atractiva.

Nubentos proporciona diversos mecanismos para publicar la documentación de tu API y hacer que ésta sea fácilmente encontrada mediante los mecanismos de búsqueda integrada.

Qué aprenderás

En este tutorial, aprenderás cómo:

• Anexar a tus APIs su documentación, mediante las diversas fuentes posibles.

Qué necesitas

Para seguir este tutorial paso a paso, debes disponer de una cuenta de Proveedor de APIs en Nubentos. Si quieres obtener acceso para convertirte en Proveedor de APIs en Nubentos, puedes solicitarlo directamente en este enlace.

Además, necesitarás lo siguiente antes de comenzar:

• La API debe estar previamente publicada en Nubentos. En nuestro blog te contamos paso a paso cómo puedes publicar tu API para Sanidad en Nubentos, fácilmente y en muy poco tiempo. Para este tutorial hemos publicado una API de ejemplo para la gestión de una clínica denominada “MedicalAPI”.
• Toda la documentación a publicar sobre tu API, ya sea documentos en diferentes formatos, enlaces a la sección de tu web para desarrolladores, o un documento de especificación de tu API para Sanidad.

Cómo documentar tu API de Sanidad

Para asociar la documentación a tu API recién publicada en Nubentos, debes seguir los siguientes pasos :

1. Accede a tu cuenta de Proveedor de APIs de Nubentos con las credenciales de acceso que te hemos entregado.
2. Asegúrate de estar en la interfaz de usuario del API Publisher de Nubentos.

3. Haz clic sobre el icono “MedicalAPI” o sobre el título de la misma, y se abrirá el detalle de la API, pestaña “Overview” .

4. Pulsa sobre la pestaña “Docs” para acceder a las diferentes opciones de publicación de documentos.

Este será tu punto de partida para agregar los diferentes tipos de documentos.

El primer documento que vas a agregar es una descripción de la API, que puedes añadir con el editor integrado. Los pasos son los siguientes.

1. Pulsa sobre le botón “Add New Document”
2. Se muestran distintos campos que debes cumplimentar:
   • Name: Daremos un nombre al documento.
   • Type: Selecciona uno de los tipos disponibles.
   • Source: La fuente del documento.
   • Summary: Una pequeña descripción resumida del contenido y/o uso del documento.

Para nuestro ejemplo usaremos los siguientes valores:

Name	MedicalAPI
Type	How To
Source	In-line
Summary	Short description of the MedicalAPI

 

3. Pulsa ahora sobre el botón “Add Document”

4. Nos indicará que el documento ya ha sido registrado pero aún no tiene contenido. Para ello pulsa sobre “Edit Content”:

5. Se abrirá una nueva ventana donde dispondrás de un editor integrado.

6. Una vez incorporado el texto pulsa en “Save and Close” .

Un segundo documento que vamos a agregar en nuestra API de ejemplo, es la guía para desarrolladores que tenemos en formato PDF. En esta ocasión los pasos son muy similares.

1. Vuelve a la pestaña “Docs” y pulsa sobre “Add new Document”
2. Rellena los campos con los siguientes datos:

Name	API Developers Guide
Type	How To
Source	File
Summary	API guide explains how you can implement some of the  most common use cases and describe concepts that you need to understand in order to use the MedicalAPI

 

3. Al pulsar sobre el check de “File” en la sección de “Source” puedes subir el fichero .pdf pulsando sobre el botón “Browse”.

4. Selecciona la ruta del fichero y pulsa nuevamente “Add Document”
5. A diferencia del documento anterior ahora tendrás la opción “Open” que descargara el documento y lo abrirá en el equipo local.

 

Por último vamos a referenciar la URL del portal de soporte de la API, donde los desarrolladores pueden hacer consultas y registrar incidencias. Los pasos son:

1. Vuelve a la pestaña “Docs” y pulsa sobre “Add new Document”
2. Cumplimenta los campos con los datos de esta tabla seleccionando como tipo “Support Forum” :

Name	MedicalAPI Support Portal
Type	Support Forum
Source	URL: www.medicalapi.com/support
Summary	Access our Support Portal in order to log a case and create a support ticket and read knowledge articles about our various software solutions

 

3. Indica la URL de soporte y pulsa sobre “Add Document”.

 

Con esto habrás añadido tres documentos a tu API para Sanidad, que seguro será una gran ayuda para los desarrolladores y un atractivo para lograr nuevos suscriptores.

Cómo se accede a la documentación de tu API

Pero, ¿cómo se verán estos recursos al otro lado del Marketplace, en el API Store? Para verlo, sigue los siguientes pasos:

1. Accede al portal de Store en https://store.nubentos.com/store
2. Selecciona la API y accede al Store de su publicador mediante el botón «Visit Publisher Store«, para acceder a la API Publicada.

3. Haz clic sobre la API Publicada , pulsa sobre “Documentation” , y podrás ver los distintos recursos que hemos cargado y que podrá ver el futuro suscriptor y consumidor de tu API.

 

De este modo tu API presentará un aspecto más profesional y será más fácil para los desarrolladores poder integrarla en sus soluciones.