Muchas veces tener una API bien diseñada no es suficiente documenta tu API usando Slate para que otros desarrolladores la utilicen de manera efectiva.
No voy a profundizar en cuáles son las mejores prácticas para documentar una API. En su lugar, iré directamente a la solución utilizada por importantes compañías como son NASA, Sony, Parrot Drones.
Slate te ayudará a documentar tu API de una forma inteligente ya que se inspira en la documentación de Stripe y PayPal y lo mejor de todo es que se adapta a cualquier dispositivo.
Gracias a las característica que Slate ofrece te permitirá configurarlo tanto como lo necesites.
Slate fue desarrollado con Middleman el cual es un generador de sitios estáticos construido con Ruby checa aquí los requerimientos para su instalación.
Ya que tenemos todos los requisitos instalados y después de haber hecho fork y clonado el proyecto principal de Slate procederemos con la configuración de nuestro ambiente local, para esto primeramente tendremos que situarnos en la carpeta raíz del proyecto y ejecutaremos el comando bundle install para instalar todas las gemas que requiere el proyecto.
Después de que se terminaron de instalar todas las dependencias ejecutaremos el servidor con el comando bundle exec middleman server el cual por defecto se ejecutara en http://localhost:4567 y nos mostrará la pagina por defecto.
Aquí podrás checar el archivo de referencia para orientarte y crear tu propia documentación.
Ya que tenemos creado nuestro archivo con la documentación de nuestra API ahora vamos a subirlo a Netlify.
Netlify es una plataforma plataforma muy conocida entre desarrolladores ya que te permite publicar sitios estáticos.
Lo primero que vamos a necesitar es crear una cuenta preferentemente con Github ya que esto te permitirá tener acceso a todos tus repositorios.
Después da clic en el botón que dice Nuevo sitio desde Git (New Site From Git)
Ahora da clic en GitHub, busca y selecciona el proyecto.
Configura las especificaciones como son la rama de tu proyecto y espera unos minutos mientras se genera tu sitio.
Eso es todo, hemos terminado de configurar nuestro sitio.
Pasos opcionales
Netlify genera un subdominio por default pero si quieres colocar tu propio dominio solo da clic donde dice Domain Settings.
Ahora da clic en add custom domain
Y por ultimo agrega tu dominio.
