Header Ads Widget

Ticker

6/recent/ticker-posts

7 generadores de documentación OpenAPI de código abierto

 


A menos que sea el único que usa la API que acaba de diseñar, realmente necesita documentarla de manera efectiva. Es probable que haya muchas decisiones que tomó al diseñar y desarrollar el servicio que podrían no ser obvias para los desarrolladores externos. Por lo tanto, hay una curva de aprendizaje muy alta para alguien que usa su API por primera vez.

El objetivo principal de la documentación de API es reducir esa curva proporcionando todo en forma simple. La excelente documentación hace que la incorporación de API sea mucho más fácil: reduce el tiempo y el esfuerzo necesarios para realizar integraciones para consumidores principiantes a consumidores avanzados.

Al mismo tiempo, un portal de API de autoservicio puede reducir el soporte al cliente requerido por el proveedor de API. Obviamente, debemos proporcionar esta documentación junto con componentes adicionales, comunidad y personal de soporte. Pero todo eso debería ser la segunda opción. Los consumidores deberían poder resolver sus problemas leyendo la documentación.

Ahora, hay dos formas en las que puede generar documentación para su API. El primero es escribir la documentación manualmente. Este método requiere mucho tiempo y esfuerzo, ya que todo se hace manualmente, desde escribir las introducciones, las versiones, hasta escribir una salida de muestra. Esta es una forma pasada de moda, pero muchos desarrolladores de API todavía siguen este método. El segundo método consiste en utilizar generadores de documentación API . Este método está completamente automatizado y requiere muy poco tiempo; con la herramienta adecuada, puede generar documentación completa en solo 5 minutos. La mayoría de las empresas con mentalidad API han cambiado a este método de alguna forma.

Beneficios de los generadores de documentos API

  • Ahorra mucho tiempo
  • También ahorra recursos
  • No es necesario que actualice el documento nuevamente cuando realice cambios, ya que estos generadores pueden detectar fácilmente los últimos cambios.
  • El control de versiones está más simplificado

¿Qué es la especificación OpenAPI?

Especificaciones de OpenAPI es un formato de descripción de API común para las API de REST. Es el estándar más ampliamente aceptado en la industria. OpenAPI, ahora en v3, define una descripción de interfaz estándar, independiente del lenguaje de programación para las API RESTful. Es impulsado por la comunidad, que se enmarca en la Iniciativa OpenAPI, un proyecto de la Fundación Linux. Con OpenAPI como columna vertebral, los proveedores de API pueden generar más fácilmente cosas como documentación, bibliotecas, entornos sandbox para pruebas y otras herramientas útiles.

Entonces, a continuación, revisaremos algunos de los mejores generadores de documentación de OpenAPI . Todos los generadores enumerados aquí son de código abierto y la mayoría son compatibles con OpenAPI v3 .

1. Redoc

Redoc es uno de los mejores generadores de documentos API de código abierto que admite las especificaciones de OpenAPI v3. Esta herramienta es poderosa y altamente personalizable. Redoc comenzó como un motor de documentación API para los documentos de Rebilly y luego se convirtió en una empresa independiente. Redoc viene en versiones gratuitas y de pago según sus requisitos. Redoc se basa en React JS y proporciona una página de tres columnas donde en la primera columna tienes tu explorador, en la segunda columna tienes la descripción del índice seleccionado, y en la última columna tienes una consola donde puedes hacer Llamadas a API.

La primera columna muestra todos los puntos finales disponibles con una pequeña insignia para indicar el método HTTP, como GET, PUT, POST, etc. La última columna también le permite generar código para llamar a la API con sus cargas útiles. Es compatible con PHP y C #. También puede habilitar y deshabilitar CORS. La herramienta también es capaz de convertir markdowna código HTML.

Redoc viene con una herramienta CLI que le permite verificar todas sus definiciones de Open API de un conjunto de reglas para asegurarse de que está siguiendo todas las mejores prácticas de OpenAPI. Una vez que esté listo para publicar los documentos, solo necesita ejecutar un solo comando.

Documentación de la API de Rebilly, con tecnología de Redoc

Clasificación de Github: 11k +

Comando de instalación: npm i redoc

Pros:

  • Mucha personalización
  • Fácil de usar
  • Diseño simple
  • Soporte para Markdown

2. DapperDox

DapperDox es otra solución de código abierto lista para usar para la documentación de API autorizada. La herramienta es muy flexible y le permite diseñar las páginas de documentación de la forma que desee. Al igual que Redoc, también admite archivos markdown.

DapperDox proporciona una interfaz de usuario ordenada y sencilla con dos columnas. En la primera columna, tiene su explorador, y en la segunda columna, tiene los detalles del método API. También le permite personalizar temas para páginas, que no están disponibles en Redoc.

Una desventaja es que DapperDox no se actualiza con frecuencia y aún no es compatible con OpenAPI v3. A partir de este problema sin respuesta , los encargados del mantenimiento están esperando una actualización de un analizador de Go.

DapperDox demuestra la especificación Petstore Swagger

Calificación de Github: 284+

Pros:

  • Opción de múltiples temas
  • Fácil de usar
  • Soporte de Markdown

3. WidderShins

WidderShins le permite crear documentación API a partir de definiciones de OpenAPI 3.0, Swagger 2.0, AsyncAPI 1.x, Semoasa 0.1.0. Gracias a las nuevas funciones introducidas en la última actualización, WidderShins ahora usa promesas en lugar de devoluciones de llamada, y ahora tiene opciones para generar HTML directamente.

La interfaz de usuario de esta herramienta es muy similar a ReDoc ya que tiene una página de tres columnas, donde en la primera columna hay un explorador, en la segunda columna tienes la descripción y en la tercera columna tienes tu consola para realizar también llamadas a la API.

WidderShins usa plantillas para generar salidas de rebajas, y puede personalizarlas según sus necesidades. Principalmente se utiliza en entornos de etapa en la canalización de desarrollo de API. WidderShins toma una definición de API, luego convierte las descripciones escritas en markdown o HTML según lo necesite el renderizador como Slate, Shins, ReSpec.

La API de Shutterstock utiliza Widdershins

Estrellas de Github: 700+

Comando de instalación:

npm install -g widdershins

Pros:

  • UI simple y limpia
  • Le permite generar HTML y rebajas

4. SwaggerUI

SwaggerUI, de Smartbear, es otra gran herramienta para generar documentación para su API. Con SwaggerUI, uno puede verificar rápidamente qué puntos finales realizan qué acciones, lo que facilita que los consumidores de API entiendan la API. SwaggerUI le permite interactuar con la API sin implementar la lógica.

Le permite crear documentación de API en múltiples formatos como JSON, YAML y markdown, lo que facilita que cualquiera pueda editarlo. A diferencia de otras herramientas, SwaggerUI tiene una vista de una sola columna donde todo se explica de forma ordenada en forma de barra plegable. SwaggerUI es compatible con la última versión de OpenAPI v3 y está bien mantenido. También funciona muy bien con otras herramientas de Smartbear, como hemos visto anteriormente.

Documentación de Swagger Petstore

Clasificación de Github: 18.8k

Comando de instalación:
npm i swagger-ui

Pros:

  • Fácil de usar
  • Puede implementar API en AWS API Gateway y AWS Lambda
  • Puede ejecutar llamadas a API desde la documentación.

5. Lucybot

Lucybot es otra herramienta de API que ayuda a los desarrolladores a comenzar con su propia API y se puede utilizar junto con la documentación de API existente. DocGen de LucyBot es un generador de sitios web estáticos para la documentación de API.

Al crear un libro de cocina en varios idiomas para todos los casos de uso principales de su API, Lucybot simplifica la exploración de las capacidades de la API. Los ejemplos de código también se expanden en una demostración de trabajo visualmente rica, por lo que los desarrolladores tienen todo lo que necesitan para comenzar a usar su API lo más rápido posible. Utiliza OpenAPI, markdown y otros estándares abiertos para crear documentación altamente personalizable, así como una consola API y tutoriales interactivos.

LucyBot proporciona una consola única para explorar las capacidades de la API

Clasificación de Github: 150+

Comando de instalación:

git clone https://github.com/LucyBot-Inc/documentation-starter

Pros:

  • Simple y fácil de usar.
  • Altamente personalizable.

6. Visor de OpenAPI

OpenAPI Viewer es un visor de especificaciones OpenAPI 3.0 y 2.0 con una consola integrada. OpenAPI Viewer funciona con cualquier marco y también sin ningún marco. Las funciones de marca y personalización facilitan el seguimiento de cualquier guía de estilo. Tiene muchas personalizaciones disponibles, como agregar contenido externo en la parte superior e inferior del documento, agregar imágenes, enlaces, formularios y mucho más.

También admite la búsqueda de puntos finales y tiene una consola integrada para probar las API. Tiene una clara separación de la información de solicitud y respuesta dispuesta una al lado de la otra en un diseño de dos columnas.

OpenAPI Viewer demuestra la especificación de API de muestra de Petstore

Estrellas de Github: 150+

Comando de instalación:

git clone https://github.com/mrin9/OpenAPI-Viewer.git

Pros:

  • Alta personalización disponible.
  • Fácil de usar.
  • Soporta autenticación.

7. RapidDoc

De toda la documentación de API en esta lista, RapidDoc tiene la mejor interfaz de usuario para la documentación de API. RapidDoc le permite crear documentación de API atractiva e interactiva utilizando especificaciones de OpenAPI. Esta herramienta es muy flexible y le permite personalizar el tema, la fuente y los colores. También puede incrustar código HTML externo en la documentación o incrustar los documentos en otro código HTML.

RapidDoc viene con una consola lista para usar, que puede usar fácilmente para realizar llamadas a la API y probar su API. Puede cambiar sus atributos usando JavaScript como lo hace en HTML. Al igual que SwaggerUI, también tiene una vista de una sola columna con barras plegables, y estas barras contienen la consola con las cargas útiles JSON.

RapidAPIDoc ofrece modo oscuro, así como otros modos de color personalizados para la documentación de API

Calificación de Github: 339+

Comando de instalación:

git clone https://github.com/mrin9/RapiDoc.git

Pros:

  • Esta herramienta tiene la interfaz de usuario más atractiva
  • Admite rebajas y HTML
  • Viene con muchos temas.

Menciones honoríficas

¿Nos perdimos algún generador de documentación de API de código abierto Open API v3? Háganoslo saber en los comentarios.

Pensamientos finales

En este artículo, hemos cubierto los generadores de documentación OpenAPI de código abierto más populares. No hay escasez de generadores de documentación en Internet, sin embargo, estas son las principales opciones de código abierto que admiten OpenAPI v3. Mantener la documentación no es una tarea fácil. Tienes que actualizar la documentación siempre que se realice un cambio en la API. Pero estas tareas no se manejan automáticamente mediante el uso de estos generadores de documentación. Ahora, los propietarios de API no tienen que preocuparse tanto por la parte de documentación y pueden centrarse por completo en el desarrollo y perfeccionamiento de la API.

Publicar un comentario

0 Comentarios