[vc_row el_class=”blog-info”][vc_column][vc_single_image source=”featured_image” img_size=”full” style=”vc_box_rounded”][vc_empty_space height=”40px”][vc_row_inner][vc_column_inner width=”1/6″][/vc_column_inner][vc_column_inner width=”2/3″][vc_column_text el_class=”font-weight-bold”]

Publicar documento OpenAPI automáticamente con NodeJS y Express

Escribir ese documento OpenAPI de especificaciones es una cosa, pero ¿cómo puede asegurarse de que sea visible para todos los que lo necesiten?

[/vc_column_text][vc_empty_space height=”40px”][/vc_column_inner][vc_column_inner width=”1/6″][/vc_column_inner][/vc_row_inner][vc_row_inner][vc_column_inner width=”1/6″][/vc_column_inner][vc_column_inner width=”2/3″][vc_column_text]

Hay muchas herramientas comerciales para compartir información de API (https://www.postman.com/ es un gran ejemplo), pero eso es algo difícil de hacer si su API es para consumo público.

¿Podrías mantener una copia en tu sitio web en algún lugar? ¿Hacer que la especificación de OpenAPI esté disponible para que la gente pueda copiar y pegar en https://editor.swagger.io/?

Probamos ambos y descubrimos que es difícil mantener una versión actualizada sin realizar una automatización adicional en la implementación.

Capacitar a las personas para que revisen el archivo del repositorio, lo copie y pegue en el editor en línea … sí, eso funciona tan bien como cabría esperar.

¿Por qué no exponer el documento OpenAPI en un formato agradable directamente en la API?

El código para hacer esto es realmente simple.

Vamos a utilizar swagger-ui-express de Stephen Scott

const express = require('express')
const swaggerUi = require('swagger-ui-express')
const router = new express.Router()
const jsYaml = require('js-yaml')
const fs = require('fs')

// Our document is YAML, if yours is JSON, then you can just
// `const openApiDocument = require('spec/openapi.json')`
// instead.
const openApiDocument = jsYaml.safeLoad(
    fs.readFileSync('spec/petstore.yaml', 'utf-8'),
)

// We can enable the explorer also!
const options = { explorer: true }
router.use('/api-docs', swaggerUi.serve)
router.get('/api-docs', swaggerUi.setup(openApiDocument, 
    options))

// If you're not using a `router`, you can use
// `app.use('/api-docs', swaggerUi.serve,
//    swaggerUi.setup(swaggerDocument, options));
....

Y eso es todo. Al iniciar nuestra aplicación y dirigirse a https://mycool.io/api-docs, debería ver algo como esto:

Ahora, cada vez que implemente su API, la última versión del documento de OpenAPI estará disponible para que todos la vean.

Espero que esto ayude a alguien a presentar la documentación de su API a las personas que la necesitan.

[/vc_column_text][/vc_column_inner][vc_column_inner width=”1/6″][/vc_column_inner][/vc_row_inner][/vc_column][/vc_row][vc_row el_class=”social-info”][vc_column width=”1/6″][/vc_column][vc_column width=”2/3″][vc_row_inner][vc_column_inner width=”1/2″][vc_column_text][social_share_button themes=’theme1′][/vc_column_text][/vc_column_inner][vc_column_inner el_class=”youtube-inner-col” width=”1/2″][vc_column_text][likebtn theme=”youtube” lang=”auto” show_like_label=”0″ white_label=”1″ alignment=”right”][/vc_column_text][/vc_column_inner][/vc_row_inner][vc_row_inner el_class=”social-info-inner”][vc_column_inner width=”1/4″][vc_single_image image=”921″][/vc_column_inner][vc_column_inner width=”3/4″][vc_column_text]

Diego Pacheco

Ingeniero en Sitemas, MBA (Babson College). Desarrollador PHP/Java/JavaScript. Fundador & CEO de EpicStudio. Entusiasta de las tecnologías web (JavaScript, Vue, Laravel, AWS, Docker) Viajes, Negocios, Surf y Growth.[/vc_column_text][asvc_list_item icon_fontawesome=”fa fa-calendar-o” icon_size=”14px”]Programar una reunión[/asvc_list_item][/vc_column_inner][/vc_row_inner][/vc_column][vc_column width=”1/6″][/vc_column][/vc_row][vc_row][vc_column][vc_column_text]

Documento OpenAPI con NodeJS y Express

Publicar documento OpenAPI automáticamente con NodeJS y Express

Diego Pacheco

Recent Post