stripe - slate documentation generator
Slate vs Swagger: ¿Cuál es mejor y cuáles tienen más opciones? (4)
Desde mi punto de vista, esas herramientas tienen propósitos muy diferentes. Swagger es un lenguaje de descripción, mientras que la pizarra es solo para documentación.
He utilizado swagger para crear una descripción, desde la cual puedo generar automáticamente diferentes clientes para mi API, incluso generar documentos automáticamente.
También puede crear Markdown desde la especificación de swagger y usar esos markdowns en Slate. [1]
Hago un frasco de pizarra ( https://github.com/AhnSeongHyun/slate-flask ) basado en un frasco de pitón.
caracteristicas:
Archivo de configuración (config.json): establezca el título, el lenguaje de programación para códigos de ejemplo utilizando config.json base en formato JSON. También establezca la ruta de los documentos de la API y la tabla de contenido (tabla de contenido).
Admite documentos Multi-API: Original Slate admite un documento API basado en el formato Markdown. Pero Slate-Flask admite documentos multi-API para una gestión eficiente y la cantidad de documentos utilizando TOC (index.json).
Admite cambios dinámicos de documentos: puede reflejar los cambios de documentos API sin reiniciar el servidor. Cuando se actualice la página web, si existen cambios, slate-flask vuelve a cargar los documentos de la API. Los usuarios solo se centran en escribir documentos API.
Swagger y Slate sirven dos propósitos diferentes. Swagger es un intento de una forma estandarizada de describir una API REST (similar, por ejemplo, a ApiBlueprint )
Swagger es un formato de definición de API basado en JSON, que permite la descripción de las API REST.
~ Herramientas de diseño API de Swagger
Slate, por otro lado, es un tema bonito para escribir buenos documentos API.
- Los dos no son mutuamente excluyentes
- Idealmente, uno debería generar su documentación de pizarra a partir de la descripción de Swagger API.
El objetivo de Swagger es proporcionar un estándar sobre el cual otros puedan construir herramientas extensivas (por ejemplo: documentación, exploradores de API, servidores simulados, generación de código, utilidades de prueba, etc.). Ver, por ejemplo: Swagger Tooling
Más a su pregunta: Algunas herramientas de pizarra para swagger:
- Aquí hay un enlace a una interfaz de usuario de Sage con temática de pizarra
- Aquí hay un proyecto que genera documentos Slate basados en la definición de Swagger.
Por lo tanto, los dos no se excluyen mutuamente, sino a su pregunta directa: la implementación de Swagger le dará más opciones y mayor flexibilidad (además de la capacidad de generar documentación de Slate).
Acerca de Slate:
- Plantilla API / Framework de documentación
- se ve bien
- facilidad de uso
- resaltado de sintaxis
- Lenguaje específico - Tabulado
- Búsqueda de páginas
- Diseño personalizable de 3 columnas.
- Podemos crear mesa.
- Enlaces desplazables a todos y cada bloques / métodos / encabezados
- Instalación de alerta [3 tipos] - advertencia, éxito, aviso
- Tablas para códigos de error http
- Sintaxis de Markdown
- Podemos usar el logo del sitio.
- Demo
Acerca de Swagger:
- Nos da acceso a la API dentro de los propios documentos, donde podemos verificar la respuesta para cualquier solicitud en particular.
- Da una imagen clara de la respuesta de la API con sus parámetros y opciones. - Formato basado en YAML
- No es adecuado para la API de hipermedia
- No hay herramientas de diseño para Swagger.
- Las respuestas están en XML o JSON.
- Swagger JS: biblioteca de JavaScript para conectarse a las API habilitadas para Swagger a través del navegador o nodejs
- Swagger Node Express - Módulo Swagger para node.js express module
- Tiene marco de UI swagger
- Demo