Header Ads Widget

Ticker

6/recent/ticker-posts

Las formas más fáciles de generar documentación de API


 Ya sea que sea una startup que está desarrollando su primera API o un jugador establecido en la economía de las API, la verdad es cada vez más evidente; Proporcionar documentación de API de calidad es vital para el éxito de una iniciativa de API. La documentación de la API es una parte importante de la oferta del producto, ya que ofrece posibilidades a la comunidad de desarrolladores para ayudarles a comprender exactamente lo que ofrece una API y cómo usarla.

En una publicación reciente sobre la diferencia entre la documentación, la especificación y la definición de la API, aclaramos el papel de la documentación: la documentación de la API es la parte que habla con los seres humanos, brindando conocimiento de su API para la comunidad de desarrolladores a través de explicaciones, muestras y ejemplos. Sin embargo, hay otra verdad simple que todo desarrollador de software conoce: todo el mundo (bueno, casi todo el mundo) odia escribir documentación y si existe la posibilidad de aliviar el dolor, entonces debería perseguirse con avidez.

En esta publicación, por lo tanto, saciamos el hambre observando las formas más fáciles de generar documentación para una API ; Independientemente de la opinión del desarrollador sobre la creación de documentación, tener un mecanismo disponible para generar documentación de API que se mantenga a la par con la naturaleza iterativa del diseño y desarrollo reducirá la carga de trabajo y también permitirá a los proveedores de API llegar al mercado más rápidamente con sus API. Sin embargo, antes de sumergirse en las posibilidades, vale la pena explorar qué es exactamente lo que la documentación de API debería ofrecer a una comunidad de desarrolladores.

Qué debe contener la documentación de la API

Por supuesto, no existen estándares o reglas estrictas sobre lo que debe abarcar la documentación de la API; como regla general, cualquier cosa que resuene en la comunidad de desarrolladores y les facilite la comprensión de una API es un buen punto de partida. Sin embargo, hay algunos temas generales que están respaldados por ejemplos de proveedores establecidos en la economía de API:

  • Una lista de los recursos con una explicación del propósito de cada uno en el contexto del producto o servicio que se ofrece a través de la API;
  • Ejemplos de llamadas a API en una variedad de lenguajes y herramientas (cURL, colecciones de Postman , etc.);
  • Guías que detallan los flujos de trabajo  implícitos en el uso de la API, es decir, la secuencia de llamadas a la API que hacen algo significativo en el contexto del producto o servicio que ofrece la API. Por ejemplo, Dwolla ofrece varias guías sobre cómo enviar o recibir dinero, con sucursales en diferentes contextos que explican los diferentes aspectos de su oferta de productos;
  • Una descripción general de los principios de diseño adoptados por el proveedor de API y lo que eso significa para los aspectos adherencia a REST (especialmente hipermedia), códigos HTTP, etc .;
  • Información sobre autenticación , incluidos los esquemas que pueden implementarse como OAuth u OpenID Connect ;
  • Información general sobre el manejo de errores con información sobre los códigos de retorno HTTP que se devolverán;
  • -Específicos del usuario contextos que los desarrolladores ayudará a entender mejor con la materia con mayor facilidad. Por ejemplo, Stripe adapta automáticamente su documentación de API con su clave y secreto de API (cuando está conectado) para que cualquier muestra de código esté lista para usar inmediatamente;
  • Un explorador de API interactivo que permite al desarrollador dar vida fácilmente a toda esta información.

Diseño de API primero

Independientemente del marco específico que un proveedor de API elija adoptar, el punto de partida para crear la documentación de la API suele ser un documento de especificación de API bien construido: esto es especialmente pertinente cuando se utiliza una metodología de diseño de primera API donde la especificación tiende a ser un resultado de el proceso. La especificación no solo constituye un producto importante para la entrega de la API, sino que puede servir como entrada para generar documentación de la API, formando la columna vertebral del contenido; muchos de los enfoques que se analizan a continuación utilizan el documento de especificaciones de API exactamente de esta manera.

Por lo tanto, es lógico pensar que si el diseño de API primero produce una especificación de API antes de escribir un fragmento de código, también permite que un proveedor de API comience el trabajo crítico de documentar su API antes, acelerando la entrega de su API. Además, como un proveedor de API itera sobre la especificación de API durante el proceso de diseño, refinándola a medida que obtienen más información sobre lo que hará que su API sea exitosa, la documentación de API puede seguir el ritmo y someterse a un proceso similar de refinamiento . El uso de una especificación de API como base para generar documentación de API, por lo tanto, proporciona una serie de enfoques diferentes; clave entre estos son:

  • Proporcionar un explorador interactivo ;
  • Creación de documentación estática ;
  • Ofrece una combinación de ambos, quizás mediante el uso de una solución de gestión de API .

Exploradores interactivos

Es cada vez más común que los formatos de especificación de API se complementen con exploradores interactivos generados a partir del propio documento de especificación, lo que crea un medio para que los consumidores aprendan y prueben las llamadas de API al mismo tiempo. Si un explorador interactivo ayuda a los desarrolladores a comprender la API de un proveedor, publicar uno es una obviedad; Por lo tanto, las opciones están determinadas en gran medida por la elección del formato de especificación de API, por ejemplo:

  • La especificación OpenAPI (también conocida como Swagger ) ofrece la interfaz de usuario Swagger , que le permite generar un explorador interactivo prácticamente sin codificación (dependiendo de la integridad de su especificación Swagger);
  • Apiary ofrece un explorador que se genera a partir de las especificaciones API Blueprint y Swagger. Combina las características de un explorador interactivo con un conjunto de documentación, ya que presenta la documentación de Markdown en API Blueprint en paralelo con una herramienta interactiva para realizar llamadas de API de muestra;
  • Finalmente, se ofrece un explorador de código abierto para el formato de especificación RAML que implementa muchas de las mismas características que Swagger UI y Apiary.

Por lo tanto, estas herramientas permiten a los proveedores de API crear rápidamente un punto de referencia fácil de usar para su comunidad de desarrolladores. Sin embargo, si el tema de la API es complejo o requiere una explicación de alto nivel no necesariamente asociada con un recurso, es posible que se requiera documentación estática para acompañar a un explorador interactivo.

Más sobre Exploradores interactivos: virtualización, entornos de prueba y áreas de juego para una API holística

Documentación estática

Existe una multitud de herramientas y tecnologías existentes que pueden ayudar a crear documentación estática a partir de datos de referencia o metadatos: Middleman , Jekyll , Hugo , por nombrar solo algunos. Sin embargo, también hay generadores de documentación estática que se centran específicamente en las API  que pueden ayudar a reducir la sobrecarga de crear documentación de API:

  • Slate es un marco que se inspiró en la apariencia de la documentación de la API para Stripe y PayPal. Muchos proveedores de API, como Travis CI y Fidor Bank, lo utilizan para crear documentación profesional y fácil de mantener que se puede personalizar y personalizar de acuerdo con los requisitos del proveedor. También hay una serie de herramientas que pueden generar documentación básica de Slate a partir de un documento de especificación de API: por ejemplo, Swagger2Slate puede generar Slate HTML a partir de un documento de Swagger;
  • También hay enfoques de cosecha propia, uno de los cuales se discutió en nuestra publicación anterior sobre diseño basado en documentación, que analiza un enfoque basado en plantillas para crear documentación de API;
  • Apiary también debe mencionarse en este contexto, dado el giro único que le dan a la combinación de un explorador interactivo con documentación estática a través de las características que lo hacen posible en API Blueprint.
Revisaremos más de 20 soluciones de documentación de API en una próxima publicación. ¡No te lo pierdas, suscríbete a nuestra newsletter!

La documentación estática es buena para llegar al meollo de la información. Sin embargo, hay otros ejemplos además de Apiary en los que se combinan exploradores interactivos y documentación estática. Esto es especialmente cierto en las soluciones de gestión de API.

Gestión de API

La gran mayoría de las soluciones de administración de API proporcionan características y funcionalidades que ayudan a los proveedores de API a generar documentación de API, combinando exploradores interactivos y documentación estática en un solo paquete . Si un proveedor de API está utilizando una solución de gestión de API , esto puede ofrecer una forma conveniente de entregar rápidamente documentación de API; sin embargo, si su solución de administración de API no implementa una característica importante y la tecnología no es extensible, un proveedor de API puede terminar usando una solución propia de todos modos. Por lo tanto, estas soluciones no deben verse como una solución milagrosa.

Las características y la funcionalidad exactas dependen del proveedor y su opinión sobre lo que es importante para la documentación de la API, pero vale la pena explorar algunos ejemplos:

  • Apigee SmartDocs es un módulo incluido con el producto Apigee Edge que crea un modelo de su API, que luego puede usarse para agregar documentación sobre las características de su API;
  • 3scale implementa una función llamada ActiveDocs , que se basa en Swagger y genera un explorador interactivo alojado en 3scale. Si bien esto puede ofrecer poco sobre la interfaz de usuario de Swagger, proporciona alojamiento listo para usar, por lo que los proveedores no necesitan buscar otras soluciones;
  • Otros productos, como Microsoft Azure API Management o la puerta de enlace Tyk de código abierto, contienen menos capacidades para generar documentación de API pero aún implementan un CMS, lo que brinda a los proveedores de API un marco para crear una experiencia rica para su comunidad de desarrolladores.
Para obtener más información, lea: Principales formatos de especificación para API REST

Reflexiones finales: personalizar para la comunidad de desarrolladores

En esta publicación hemos analizado lo que implica la creación de documentación de API y las diferentes formas de abordar la tarea. Como dijimos anteriormente en la publicación, no existen estándares estrictos para la documentación de API; muchos proveedores de API implementan funciones que son exclusivas para ellos.

Al implementar su propia documentación de API, considere los temas generales y las estrategias potenciales descritas en esta publicación, pero sobre todo cree un conjunto de documentación que toque la fibra sensible de su comunidad de desarrolladores . Ante todo, como proveedor de API, debe ser muy consciente de lo que busca su audiencia, así como de su valor único, así que busque los temas que le parezcan adecuados.

Publicar un comentario

0 Comentarios