Header Ads Widget

Ticker

6/recent/ticker-posts

Más de 8 generadores de documentación AsyncAPI


Básicamente, hay dos tipos de API web: síncronas y asíncronas. Las API síncronas devuelven datos instantáneamente, proporcionando una forma de obtener datos de forma inmediata o programada. Siempre que llama a una API síncrona, se bloquea hasta que el servidor devuelve una respuesta. La aplicación que solicitó los datos espera a que la API produzca una respuesta.

En las API asincrónicas, se ejecuta una función de devolución de llamada cuando se devuelve una respuesta de la API. La llamada a la API no bloquea la aplicación y la aplicación no espera a que la API devuelva la respuesta; por lo tanto, continúa ejecutando otras funcionalidades. Estas API son útiles para aquellas aplicaciones que tienen que cargar otros componentes que no dependen de la API.

¿Qué es AsyncAPI?

AsyncAPI es una definición de API respaldada por una iniciativa de código abierto para definir API asíncronas controladas por eventos. Como OpenAPI define los detalles de una API REST, AsyncAPI define las complejidades de una API asincrónica. Las especificaciones de AsyncAPI están inspiradas en las especificaciones de OpenAPI (anteriormente conocido como Swagger) y describen y documentan la API asíncrona impulsada por eventos en un formato legible por máquina.

Por ejemplo, cuando usa WebSockets o cuando dos servicios diferentes se comunican entre sí a través de un intermediario de mensajes, no puede usar API síncronas aquí porque debe haber un flujo de datos bidireccional, que no se comunica a través de HTTP. Esto se conoce como un sistema full-duplex en el que el cliente y el servidor están conectados entre sí de manera persistente. El cliente no necesita hacer ping al servidor una y otra vez para obtener los nuevos datos. Siempre que los datos se envían al servidor, los envía automáticamente al cliente.

Aquí es donde entra en juego AsyncAPI, ya que OpenAPI solo atiende a API HTTP como REST. AsyncAPI encaja bien con protocolos como AMQP, Kafka, MQTT, etc. Puede consultar nuestro artículo sobre 7 protocolos buenos para documentar con Async API , donde hemos discutido estos protocolos en detalle.

¿Por qué documentar una API asincrónica?

Cuando esté creando diferentes puntos finales de API, llegará un punto en el que empezará a olvidar el nombre de esos puntos finales de API. Además, desde un punto de vista comercial, no eres el único que lo consumirá, ¿verdad? Por lo tanto, es una buena práctica documentar todas las API que crea, explicando cada punto final para ayudar a los futuros consumidores de API . Esto hará que su API sea fácil de entender y le permitirá concentrarse en un mayor desarrollo y mejora.

Algunos otros beneficios incluyen:

  • La documentación mejora la tasa de adopción de API.
  • La documentación facilita que el equipo de desarrollo (y los nuevos miembros del grupo) comprendan la API y cómo funciona.
  • La documentación ahorra mucho tiempo y dinero de soporte para la empresa.
  • La documentación facilita el mantenimiento de la API.

Principales generadores de documentación de API asíncronas

Si está utilizando AsyncAPI y desea documentar su API, lo tenemos cubierto. Hemos seleccionado una lista de generadores de documentación de API Async para ayudar:

Widdershins

Widdershins es uno de los generadores de documentación más populares que admite AsyncAPI. Admite formato HTML y ReSpec directamente desde el primer momento. La mayoría de las veces, se utiliza como escenario para documentar las API. Le permite generar fragmentos de código en NodeJS, JavaScript, Shell, Ruby, Python y Java, y el documento generado es completamente compatible con dispositivos móviles, lo que significa que admite diferentes tamaños de pantalla. Una de las mejores partes de Widdershins es que le permite usar promesas en lugar de devoluciones de llamada, lo cual es relativamente nuevo. También admite otras definiciones de API como Open API 3.0, OpenAPI 2.0, formato Semoasa de RepreZen y API Blueprint.

Widdershins usa plantillas para generar el archivo de rebajas. Estas plantillas son completamente personalizables y muy fáciles de administrar. Algunas de las empresas que utilizan Widdershins son Shutterstock, Capital One, Open EO y otras.

  • Comando para instalar WidderShins: npm install -g widdershins
  • Vea una vista previa en vivo: https://api-reference.shutterstock.com/#overview

Generador

Generator es otra de las mejores opciones de documentación de la API Async. Según su sitio web, te permite generar lo que quieras. Lo que realmente quieren decir es que puede generar documentación HTML, código NodeJS y documentación Markdown. Utiliza un sistema de plantillas para generar documentación para las API. Para generar documentación de API, tendrá que crear una plantilla y luego usar esa plantilla para crear páginas. Hay pocas plantillas pre-generados disponibles para el generador como asyncapi/nodejs-templateasyncapi/nodejs-ws-templateasyncapi/java-spring-templateetc.

  • Comando para instalar Generator: npm install -g @asyncapi/generator

api2html

api2html es una herramienta CLI que se utiliza para generar documentación AsyncAPI utilizando datos API sin procesar. Admite diferentes definiciones de API como Open API, AsyncAPI y Swagger y genera documentación HTML. El generador de documentación admite 33 idiomas (no lenguaje de programación) y puede servir páginas estáticas y dinámicas. Una de las mejores partes de api2html es que usa el Cache-Controlencabezado para realizar solicitudes de API. Entonces, si realiza solicitudes de API a través de api2html, guardará la respuesta de la caché durante un período de tiempo específico. El consumo de recursos de este generador de documentación es muy bajo (alrededor de 15 MB), por lo que no tiene que preocuparse por el bloqueo del servidor si lo aloja en el mismo servidor que la API.

  • Comando para instalar api2html: npm i api2html -g
  • Mira la vista previa en vivo: https://tobilg.github.io/api2html/petstore/#swagger-petstore

Protuberancia

Bump es otro generador de documentación Async que usa acciones de GitHub para generar y sincronizar la documentación con la API automáticamente. Es compatible con la definición de OpenAPI y AsyncAPI. Quizás se esté preguntando: ¿qué son las acciones de GitHub? Se utilizan para automatizar los flujos de trabajo de desarrollo de software. Esto le permite compilar, probar, implementar su código en GitHub y realizar un seguimiento de los cambios de código. La interfaz de usuario de la herramienta de documentación es muy limpia y sirve como una aplicación de una sola página.

  • Descarga Bump: https://bump.sh/
  • Vea la vista previa en vivo: https://docs.canopyservicing.com/

Springwolf

Springwolf es un generador de documentación de API Async que está inspirado en SpringFox, otro generador de documentación de API para API REST basado en Spring y JSON. SpringWolf se utiliza para generar documentación de API basada en Spring Boot y sigue las definiciones de AsyncAPI. Genera documentación de API, que tiene ejemplos de carga útil generados automáticamente y una interfaz de usuario fácilmente personalizable. Puede generar automáticamente documentación de API usando anotaciones de escucha como @kafkalistenerEsta documentación de la API es útil para los consumidores de Kafka.

  • Comando para instalar SpringWolf: git clone https://github.com/springwolf/springwolf-core.git
  • También puede consultar una vista previa en vivo en: https://springwolf.github.io/springwolf-ui/

Paseo

Saunter es otro generador de documentación de API que se utiliza para las API de .NET. Saunter actualmente admite enlaces HTTP y enlaces Kafka. Este generador de documentación AsyncAPI está inspirado en Swashbuckle, que es otro generador de documentación de API .NET pero para API REST.

  • Comando para instalar Saunter: dotnet add package Saunter
  • Puede ver la vista previa en vivo en: https://github.com/tehmantra/saunter

Scribano

Scribano se usa para generar documentación para AsyncAPIs que usan RabbitMQ. Realiza un seguimiento de todos los mensajes recibidos y enviados mediante RabbitMQ y sigue actualizando la API basada en la definición de AsyncAPI en la que se sirve /asyncapiRabbitMQ es un intercambio de mensajes y Scribano recibe todos los mensajes de él. Después de recibir los mensajes, genera y sirve la documentación en la /asyncapiruta.

  • Comando para instalar Scribano: git clone https://github.com/uesteibar/scribano.git

AsyncAPI React

AsyncAPI React es un componente oficial de ReactJS para documentar AsyncAPI. Puede integrar sus propios componentes React personalizados en este generador de documentación para que se vea más hermoso. AsyncAPI React viene con una aplicación Playground que te permite probar la API sobre la marcha. También le permite usar componentes angulares para realizar más cambios de personalización.

  • Comando para instalar AsyncAPI React: npm install --save @asyncapi/react-component
  • También puede consultar la vista previa en vivo en: https://asyncapi.github.io/asyncapi-react/

Menciones honoríficas

¿Dejamos fuera un generador de documentación AsyncAPI? ¡Comente a continuación y consideraremos agregarlo a nuestra lista!

Ultimas palabras

En este artículo, intentamos incluir las mejores soluciones de documentación AsyncAPI para generar documentación para sus API asincrónicas. Cada uno tiene sus diferentes requisitos y estos generadores de documentación pueden cumplirlos. Algunas de estas herramientas de documentación de API pueden ayudarlo a ejecutar sus API sobre la marcha. Por lo tanto, depende de sus requisitos y del objetivo final que desee alcanzar con estas herramientas. También hemos cubierto algunas de las mejores herramientas de documentación de OpenAPI V3 ; compruébalo también si quieres documentar tu API REST.

Publicar un comentario

0 Comentarios