Desarrollar una API es una tarea, pero la documentación es otro gran esfuerzo en sí mismo. Se necesita mucho tiempo para crear documentación que sea fácil de entender e implementar. Afortunadamente, estándares como la especificación OpenAPI hacen posible facilitar el proceso de creación de la documentación de la API.
En este tutorial, cubriremos cómo generar automáticamente documentación de API a partir de una definición de OpenAPI. Para esto, usaremos Redoc , la herramienta gratuita de documentación de API de código abierto de Redocly. Mostraremos cómo generar documentación de API impresionante con OpenAPI y detallaremos cómo personalizar la apariencia de su documentación.
Características de la especificación OpenAPI
En primer lugar, ¿qué es OpenAPI? La especificación OpenAPI (OAS), anteriormente conocida como Swagger, es una especificación estándar de código abierto para describir las API REST. Para que los clientes y servidores que utilizan API REST interactúen, una Especificación de OpenAPI sirve como contrato, que establece los métodos y la documentación de la API.
OpenAPI es independiente del idioma, lo que permite a los desarrolladores comprender y utilizar los servicios sin saber cómo funciona el servidor o acceder al código del servidor. Puede ayudar a crear documentación API y entregables de contenido técnico visualmente atractivos y atractivos que expliquen cómo funciona la API.
Además, OpenAPI le permite evaluar cada componente de su marco a medida que avanza a través del flujo de trabajo de diseño de API. Esto es posible porque las definiciones de OpenAPI son legibles por máquina y pueden usarse para evaluar la consistencia de una API. OpenAPI tiene una amplia base de usuarios respaldada por muchas organizaciones populares como Google, IBM, eBay, Microsoft y muchas más. Debido a la adopción generalizada de la especificación OpenAPI, se ha desarrollado un extenso ecosistema de herramientas .
¿Por qué Redoc.ly?
Como hemos cubierto anteriormente, Redoc es un generador de documentación de código abierto para las especificaciones de OpenAPI. La herramienta es altamente personalizable y viene con planes gratuitos y pagos. El generador de documentación se basa en React JS y responde. Algunas características incluyen:
- Fácil de usar
- El soporte para integraciones de línea de comandos agrega funciones para usuarios avanzados
- Diseño receptivo de tres paneles que aloja mucha información en una sola página
- Soporte para múltiples lenguajes, incluidos PHP, CURL, Node.JS y Python
- Compatibilidad con versiones anteriores para Open API Spec, compatible con OpenAPI v2 y OpenAPI v3
Prerrequisitos
Ahora, sigamos adelante con la generación de documentación de API. Para este tutorial, necesitará:
- Conocimiento de HTML, JS, CSS
- Archivo de especificación de OpenAPI alojado en una URL pública
Paso 1: Cargue su archivo de especificación de OpenAPI a una URL de acceso público como Git
Para este tutorial, usaremos esta URL de Git . La ventaja de usar Git es que te permite generar una URL pública que cualquiera puede compartir y usar.
Puede escribir su Especificación de OpenAPI y cargarla en git y asegúrese de copiar la URL pública.
Paso 2: creación de la interfaz de usuario de la documentación
Ahora cree un archivo llamado test.htmly ábralo en su editor de código favorito. Después de eso, pega el siguiente código:
<!DOCTYPE html>
<html>
<head>
<title>ReDoc</title>
<!-- needed for adaptive design -->
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
<!--
ReDoc doesn't change outer page styles
-->
<style>
body {
margin: 0;
padding: 0;
}
</style>
</head>
<body>
<redoc spec-url='YOUR_PUBLIC_URL_HERE'></redoc>
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
</body>
</html>Nota : Reemplace YOUR_PUBLIC_URL_HEREcon su URL pública, no la secreta.
Explicación del código
Estamos usando el método CDN aquí, por lo que no tiene que preocuparse por la parte de dependencia. También estamos usando Google Fonts CDN, que nos ayudará a agregar estilos a nuestra documentación. Puede usar cualquier otra fuente que desee, pero por ahora, estamos usando la Montserratfuente.
Después de cargar todos los estilos y nuestra especificación OpenAPI, al final, llamamos a Redoc CDN para hacer la magia:
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>Paso 3: probar la documentación
Ahora, abra el test.htmlen su navegador y debería ver algo como esto:
¡Eso es! ¡Finalmente ha generado su documentación de API usando Redoc!
Paso 4: agregar un logotipo personalizado
La mayor parte de la documentación de API pertenece a una empresa específica, ¿verdad? Y la empresa tiene un logo único para identificarlo. Intentemos agregar un logotipo a nuestra documentación. Para hacerlo, actualice su YAMLarchivo y luego agregue las siguientes líneas en la sección de información:
x-logo:
url: "https://raw.githubusercontent.com/vyomsrivastava/redoc-ly/main/logo.png"
backgroundColor: "#FFFFFF"
altText: "Petstore logo"
Explicación del código:
El x-logoes un objeto info que toma como parámetros url, backgroundColory altTextpor el estilo. Así que solo necesitas subir el logo y pasarlo en los parámetros.
Alojamiento de la documentación
Alojar la documentación de Redoc es muy fácil ya que son archivos estáticos. Por lo tanto, puede utilizar cualquier proveedor de alojamiento web. Solo necesita cargar el index.htmlarchivo, que tiene el script para llamar a los redocscripts. Puede colocar el archivo YAML en una URL pública de Git o simplemente colocarlo en un servidor web y pasar la URL en el archivo HTML.
Escalar la documentación
La especificación de OpenAPI, que se encuentra en la versión 3.1.0 en el momento de escribir este artículo, especifica una definición de interfaz estándar e independiente del lenguaje de programación para las API RESTful. En lugar de componentes XML, OpenAPI usa una colección de objetos JSON, cada uno con su esquema que especifica su nombre, orden y contenido. Todo lo que esté dentro de la palabra clave 'esquema' en OpenAPI se describe mediante el objeto de esquema.
Una de las mejores características de este generador de documentación es la escalabilidad. Puede agregar fácilmente nuevos puntos finales de API simplemente actualizando YAML o JSON sin realizar ningún cambio en el archivo HTML. Por tanto, esto convierte a Redoc en uno de los mejores generadores de documentación.
Ultimas palabras
La documentación es un paso crucial en el proceso de desarrollo de API. El uso de la especificación OpenAPI proporciona varios beneficios a los desarrolladores de API, así como a las empresas cliente. Proporciona a los desarrolladores un punto de referencia para diseñar API colaborativas, innovadoras y comprobables que mejoran su experiencia y les permite ofrecer productos API de alta gama a los usuarios finales.
No solo esto, sino que con la ayuda de la especificación OpenAPI, puede ahorrar tiempo y evitar errores al escribir código. Se puede convertir en código utilizando cadenas de herramientas estándar o modificadas, lo que permite ahorrar tiempo y esfuerzo.
Redoc le permite generar documentación utilizando la especificación OpenAPI de forma muy rápida y automática. También le permite integrar su CSS y estilo para que coincida con su producto.
0 Comentarios
Dejanos tu comentario para seguir mejorando!