Acerca de OpenAPI
OpenAPI es una especificación que se usa para describir las interfaces de API de REST. Describe la API sin necesidad de acceso al código fuente ni a documentación adicional. La especificación es legible tanto por humanos como por máquinas. Para obtener más información, consulta la documentación de especificación de OpenAPI.
Acerca de la descripción de OpenAPI de GitHub
La descripción de OpenAPI de GitHub de la API de REST está disponible públicamente. Puedes encontrar la descripción en el repositorio de código abierto github/rest-api-description.
GitHub proporciona descripciones de OpenAPI 3.0 y 3.1.
Para cada descripción, existe una versión de cada producto: GitHub Free/GitHub Pro/GitHub Team (api.github.com), GitHub Enterprise Cloud (ghec) y cada versión de GitHub Enterprise Server (ghes-X.X).
Para cada producto, si se admite el control de versiones basado en fechas, también hay una descripción para cada versión basada en fechas. Para más información, consulta «Versiones de API» en la documentación de GitHub Free.
Cada descripción está disponible en un formato agrupado o desreferenciado. El formato agrupado usa $ref para hacer referencia a los componentes de OpenAPI que se comparten entre puntos de conexión. El formato desreferenciado incluye la descripción totalmente expandida.
Utilizar la descripción de OpenAPI de GitHub
Dado que la descripción de OpenAPI es legible por máquina, puede usarla para hacer cosas como las siguientes:
- Generar bibliotecas para facilitar el uso de la API de REST
- Validar y probar una integración que usa la API de REST
- Explorar e interactuar con la API de REST mediante herramientas de terceros como Insomnia o Postman
Por ejemplo, GitHub usa la descripción de OpenAPI para generar los SDK de Octokit. GitHub también usa la descripción de OpenAPI para generar la documentación de referencia de la API de REST para cada punto de conexión.