From be89d271080a4bd5ac4543c19c105dec7a6dc54a Mon Sep 17 00:00:00 2001 From: Sarah Edwards Date: Mon, 13 Nov 2023 09:52:23 -0800 Subject: [PATCH] Update the OpenAPI decription article (#45779) Co-authored-by: Kevin Heis --- ...he-openapi-description-for-the-rest-api.md | 39 +++++++++++++++++++ content/rest/overview/index.md | 3 +- content/rest/overview/openapi-description.md | 30 -------------- 3 files changed, 41 insertions(+), 31 deletions(-) create mode 100644 content/rest/overview/about-the-openapi-description-for-the-rest-api.md delete mode 100644 content/rest/overview/openapi-description.md diff --git a/content/rest/overview/about-the-openapi-description-for-the-rest-api.md b/content/rest/overview/about-the-openapi-description-for-the-rest-api.md new file mode 100644 index 000000000000..d5c42847d1a3 --- /dev/null +++ b/content/rest/overview/about-the-openapi-description-for-the-rest-api.md @@ -0,0 +1,39 @@ +--- +title: About the OpenAPI description for the REST API +shortTitle: OpenAPI description +intro: 'The {% data variables.product.product_name %} REST API is fully described in an OpenAPI compliant document.' +versions: + fpt: '*' + ghes: '*' + ghec: '*' +topics: + - API +redirect_from: + - /rest/overview/openapi-description +--- + +## About OpenAPI + +OpenAPI is a specification for describing REST API interfaces. It describes the API without requiring access to the source code or additional documentation. The specification is both human and machine readable. For more information, see [the OpenAPI specification documentation](https://spec.openapis.org/oas/v3.1.0). + +## About {% data variables.product.company_short %}'s OpenAPI description + +{% data variables.product.company_short %}'s OpenAPI description of the REST API is publicly available. You can find the description in the open source [github/rest-api-description](https://github.com/github/rest-api-description) repository. + +{% data variables.product.company_short %} provides both 3.0 and 3.1 OpenAPI descriptions. + +For each description, there is a version for each product: {% data variables.product.prodname_free_user %}/{% data variables.product.prodname_pro %}/{% data variables.product.prodname_team %} (`api.github.com`), {% data variables.product.prodname_ghe_cloud %} (`ghec`), {% data variables.product.prodname_ghe_managed %} (`github.ae`), and each version of {% data variables.product.prodname_ghe_server %} (`ghes-X.X`). + +For each product, if date-based versioning is supported, there is also a description for each date-based version. For more information, see {% ifversion api-date-versioning%}"[AUTOTITLE](/rest/overview/api-versions)."{% else %}"[AUTOTITLE](/free-pro-team@latest/rest/overview/api-versions)" in the {% data variables.product.prodname_free_user %} documentation.{% endif %} + +Each description is available in a bundled or in a dereferenced format. The bundled format uses `$ref` to refer to OpenAPI components that are shared between endpoints. The dereferenced format includes the fully expanded description. + +## Using the {% data variables.product.company_short %} OpenAPI description + +Because the OpenAPI description is machine readable, you can use it to do things like: + +- Generate libraries to facilitate using the REST API +- Validate and test an integration that uses the REST API +- Explore and interact with the REST API using third-party tools, such as Insomnia or Postman + +For example, {% data variables.product.company_short %} uses the OpenAPI description to generate the Octokit SDKs. {% data variables.product.company_short %} also uses the OpenAPI description to generate the REST API reference documentation for each endpoint. diff --git a/content/rest/overview/index.md b/content/rest/overview/index.md index 98b99f374d94..9dbc8ee6c953 100644 --- a/content/rest/overview/index.md +++ b/content/rest/overview/index.md @@ -19,7 +19,7 @@ children: - /keeping-your-api-credentials-secure - /troubleshooting - /libraries-for-the-rest-api - - /openapi-description + - /about-the-openapi-description-for-the-rest-api - /issue-event-types - /github-event-types - /endpoints-available-for-github-app-installation-access-tokens @@ -31,3 +31,4 @@ children: redirect_from: - /developers/overview --- + diff --git a/content/rest/overview/openapi-description.md b/content/rest/overview/openapi-description.md deleted file mode 100644 index c83bc08e786c..000000000000 --- a/content/rest/overview/openapi-description.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: OpenAPI description -intro: 'The {% data variables.product.product_name %} REST API is fully described in an OpenAPI 3.0 compliant document.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API ---- - -## About OpenAPI descriptions - -[OpenAPI](https://swagger.io/docs/specification/about/) is a standard specification for describing REST APIs. OpenAPI descriptions allow both humans and machines to discover the capabilities of an API without needing to first read documentation or understand the implementation. {% data variables.product.company_short %} has made its REST API publicly available as an OpenAPI 3.0 compliant document. - -## Getting the {% data variables.product.company_short %} OpenAPI description - -You can find the description in the open source [REST API OpenAPI Description](https://github.com/github/rest-api-description) repository. - -We provide the description in two formats. The bundled version works for most cases, as it includes OpenAPI components for reuse and readability. If your tooling does not support inline references to components, we also provide a fully dereferenced version. - -## Using the {% data variables.product.company_short %} OpenAPI description - -There are many uses for an OpenAPI description. For example, you could: - -- Generate your own API client. -- Validate and test a {% data variables.product.company_short %} REST API integration. -- Explore and interact with the {% data variables.product.product_name %} REST API using third-party tools, such as Insomnia or Postman. - -For example, {% data variables.product.company_short %} uses the REST OpenAPI description to generate the {% data variables.product.product_name %} [REST API reference documentation](/rest).