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.