feat: add type annotations with examples and annotations about stri…

…ngs' `formats`, where available (and other improvements) (#202)

cache/api.github.com.json

@@ -1,7 +1,7 @@
 {
  "openapi": "3.0.3",
  "info": {
- "version": "6.5.0",
+ "version": "6.6.2",
  "title": "GitHub's official OpenAPI spec + Octokit extension",
  "description": "OpenAPI specs from https://github.com/github/rest-api-description with the 'x-octokit' extension required by the Octokit SDKs",
  "license": { "name": "MIT", "url": "https://spdx.org/licenses/MIT" },
@@ -1239,6 +1239,18 @@
  "type": "string"
  }
  }
+ },
+ "examples": {
+ "default": {
+ "summary": "Create an authorization",
+ "value": {
+ "scopes": ["public_repo"],
+ "note": "optional note",
+ "note_url": "http://optional/note/url",
+ "client_id": "abcde12345fghij67890",
+ "client_secret": "3ef4ad510c59ad37bac6bb4f80047fb3aee3cc7f"
+ }
+ }
  }
  }
  }
@@ -1289,7 +1301,7 @@
  "description": "API method documentation",
  "url": "https://docs.github.com/rest/reference/oauth-authorizations#get-or-create-an-authorization-for-a-specific-app"
  },
- "parameters": [{ "$ref": "#/components/parameters/client-id" }],
+ "parameters": [{ "$ref": "#/components/parameters/oauth-client-id" }],
  "requestBody": {
  "required": true,
  "content": {
@@ -1324,6 +1336,17 @@
  },
  "required": ["client_secret"],
  "type": "object"
+ },
+ "examples": {
+ "default": {
+ "summary": "Create an authorization for an app",
+ "value": {
+ "client_secret": "3ef4ad510c59ad37bac6bb4f80047fb3aee3cc7f",
+ "scopes": ["public_repo"],
+ "note": "optional note",
+ "note_url": "http://optional/note/url"
+ }
+ }
  }
  }
  }
@@ -1393,7 +1416,7 @@
  "url": "https://docs.github.com/rest/reference/oauth-authorizations#get-or-create-an-authorization-for-a-specific-app-and-fingerprint"
  },
  "parameters": [
- { "$ref": "#/components/parameters/client-id" },
+ { "$ref": "#/components/parameters/oauth-client-id" },
  {
  "name": "fingerprint",
  "in": "path",
@@ -1431,6 +1454,17 @@
  },
  "required": ["client_secret"],
  "type": "object"
+ },
+ "examples": {
+ "default": {
+ "summary": "Create an authorization for an app and fingerprint",
+ "value": {
+ "client_secret": "3ef4ad510c59ad37bac6bb4f80047fb3aee3cc7f",
+ "scopes": ["public_repo"],
+ "note": "optional note",
+ "note_url": "http://optional/note/url"
+ }
+ }
  }
  }
  }
@@ -10293,6 +10327,7 @@
  },
  "exclude": {
  "type": "array",
+ "description": "Exclude related items from being returned in the response in order to improve performance of the request. The array can include any of: `\"repositories\"`.",
  "items": { "type": "string", "enum": ["repositories"] }
  }
  },
@@ -41698,6 +41733,14 @@
  },
  "required": ["repositories"],
  "type": "object"
+ },
+ "examples": {
+ "default": {
+ "value": {
+ "repositories": ["octocat/Hello-World"],
+ "lock_repositories": true
+ }
+ }
  }
  }
  }
@@ -86319,6 +86362,14 @@
  "required": true,
  "schema": { "type": "string" }
  },
+ "oauth-client-id": {
+ "name": "client_id",
+ "in": "path",
+ "required": true,
+ "description": "The client ID of the OAuth app.",
+ "schema": { "type": "string" },
+ "examples": { "default": { "value": "abcde12345fghij67890" } }
+ },
  "authorization-id": {
  "name": "authorization_id",
  "description": "The unique identifier of the authorization.",