how create api documentation postman
Este tutorial explica cómo crear documentación atractiva y con estilo con un esfuerzo mínimo utilizando el soporte de documentación API proporcionado por la herramienta Postman:
Para cualquier API, ya sea interna o pública, la documentación es uno de los ingredientes más esenciales para su éxito.
La razón principal de esto es que la documentación es la forma en que se comunica con sus usuarios.
- ¿Cómo debería usarse tu API?
- ¿Qué todos los códigos de estado son compatibles?
- ¿Cuáles son los códigos de error?
- ¿Cuáles son todos los tipos de métodos expuestos?
Toda esta información es necesaria para que cualquiera pueda usar o implementar la API para la necesidad deseada.
=> Tenga cuidado con la serie de capacitación simple cartero aquí.
cómo comparar archivos en linux
Postman proporciona una metodología de documentación fácil de usar y, para la documentación básica, es tan simple como hacer clic en un botón a través de la colección Postman y puede obtener una URL pública para la documentación de su API.
Lo que vas a aprender:
Creación de documentación de API en Postman
Funciones de documentación
Las características destacadas del generador de documentación Postman incluyen:
- Es compatible con la sintaxis de rebajas. Markdown es una sintaxis de documentación genérica, que normalmente deberías haber notado en cualquier proyecto de Github. Permite hacer que el estilo y el formato de texto sean más familiares y fáciles.
- Sin sintaxis / requisitos específicos para la creación de documentación. La información de solicitud y recopilación se utiliza de la mejor manera para generar documentación.
- Puede publicarse en una URL pública o en un dominio personalizado (para usuarios empresariales).
- Genera fragmentos de código para realizar llamadas a la API en diferentes lenguajes como C #, PHP, Ruby, Python, Node, etc.
Creación de documentación
El generador de documentos de Postman se refiere a la colección, la carpeta y la descripción de la solicitud individual y las recopila mientras crea o genera documentación para la colección.
Hace uso de varios parámetros de solicitud como encabezados, parámetros de cadena de consulta, parámetros de formulario e indica el uso de estos valores en la documentación de la solicitud.
Aquí hay un tutorial en video:
Creemos una colección básica con 3 solicitudes utilizando la misma API de prueba que nuestros otros artículos. Agregaremos algo de información a la descripción de la colección, así como a las solicitudes individuales y también crearemos algunas solicitudes y respuestas de ejemplo, que también se capturarán al crear la documentación.
Siga los pasos a continuación para agregar información básica sobre las solicitudes y luego crear la documentación.
#1) Cree una colección con 3 solicitudes, es decir, registrar usuario, iniciar sesión y obtener usuario (consulte aquí para solicitudes de cargas útiles y URL de API).
#2) Ahora agreguemos algo de información en formato de rebajas a la colección. Markdown es un formato estándar que se utiliza para casi toda la documentación en Github (para obtener más información sobre Markdown, consulte aquí ).
Agregaremos información a la descripción de la colección en el formato de descuento como se muestra a continuación.
Para obtener una vista previa de cómo se ve la rebaja, consulte el portal web de código abierto aquí.
#3) Ahora agregaremos las descripciones a las solicitudes individuales en la colección. Similar a la colección, el formato de rebajas también es compatible con las descripciones de las solicitudes (para obtener información más detallada sobre la guía de rebajas, consulte aquí ).
Veamos una muestra de una de las solicitudes de extremo de registro de usuario (lo mismo se puede aplicar a otras solicitudes también).
Texto de rebaja:
|_+_|Vista previa de Markdown:
#4) Para todos los puntos finales de la API, capturemos o guardemos un ejemplo que usaría el generador de documentación.
Un ejemplo no es más que una muestra de solicitud-respuesta para la solicitud de API en consideración. Guardar la respuesta como ejemplo permite al generador de documentación capturarla como parte de la propia documentación.
Para guardar un ejemplo, presione el 'Enviar' para ejecutar la solicitud y en la pestaña de respuesta, haga clic en Guardar respuesta -> Guardar como ejemplo .
Una vez que se guarda el ejemplo, se conserva en la colección y se puede acceder a él en cualquier momento en el futuro a través de un Ejemplos enlace en el generador de solicitudes.
#5) Una vez agregada toda la información anterior, veamos cómo crear una vista previa de la documentación.
Abra las opciones de colección y haga clic en ' Publicar documentos ”.
Nota: Una cosa importante a tener en cuenta aquí es que solo los usuarios registrados con Postman podrán usar la función Publicar documentos en Postman. El registro es gratuito pero debe hacerse a través de su cuenta de correo electrónico. Hay otras capacidades / características como compartir colecciones y espacios de trabajo, crear monitores, etc., que se agregan a las cuentas registradas.
#6) Una vez ' Publicar documentos ', Se abre una pestaña del navegador con los detalles de la colección de Postman (internamente Postman aloja esta colección en sus propios servidores, además del sistema de archivos local del usuario).
Haga clic en 'Avance' para ver la documentación antes de que se publique.
“ Publicar colección ”Publicará la documentación en una URL de acceso público. Por lo general, no se recomienda publicar API que tengan información de autorización confidencial para publicar en la URL pública. Estas API se pueden publicar utilizando dominios personalizados con cuentas empresariales de Postman.
#7) Veamos cómo se ve la vista previa de la documentación. Haciendo clic en ' Vista previa de la documentación 'Abre la documentación en un modo de vista previa alojada en los servidores de Postman. Veamos qué diferentes detalles se capturan en la documentación (como configuramos en diferentes lugares. Por ejemplo , descripción de la colección, descripción de la solicitud y ejemplos).
En las 2 capturas de pantalla anteriores, puede ver que toda la información que se agregó a la colección y las descripciones de las solicitudes se capturan con un estilo de rebajas en la vista previa de la documentación.
convertidor de youtube a mp4 descarga gratuita de la versión completa
Además, la documentación de forma predeterminada proporciona enlaces de idioma resaltados y eso hace que sea mucho más fácil para alguien que desee realizar directamente la solicitud de API en el idioma de la lista.
#8) También le permite realizar modificaciones de estilo muy básicas como cambiar el color de fondo, cambiar el color de fondo y de primer plano de las plantillas de encabezado, etc. Pero en general, la vista predeterminada en sí es suficiente para publicar un conjunto de documentación realmente bueno que capture una gran cantidad de detalles importantes sobre la API.
Conclusión
En este tutorial, analizamos el soporte de documentación de API proporcionado por Postman, con el cual podemos crear una documentación con estilo y atractivo con un mínimo esfuerzo.
También permite muchas buenas plantillas y estilos definidos por el usuario que podrían aplicarse a los documentos generados y también permite publicar documentación en una URL pública.
Para los puntos finales de API privados, también existe una disposición para publicar documentación en un dominio personalizado que podría configurarse para las cuentas o los usuarios de la empresa.
Más lecturas = >> Cómo publicar Pact Contract to Pact Broker
=> Visite aquí para aprender cartero desde cero.
Lectura recomendada
- Tutorial POSTMAN: Pruebas de API con POSTMAN
- ¿Cómo y cuándo utilizar los scripts de solicitud previa y posterior de Postman?
- ¿Cómo utilizar Postman para probar diferentes formatos de API?
- ¿Cómo utilizar la integración de la línea de comandos con Newman en Postman?
- Tutorial de la API de descanso: restricciones y arquitectura de la API de REST
- Genere documentación viva con Pickles para archivos de características Specflow
- Automatización de la validación de respuestas con afirmaciones en Postman
- Códigos de respuesta de la API de descanso y tipos de solicitudes de descanso