api 5.0.0-beta.1 → 5.0.0-beta.2

package/README.md

@@ -1,179 +1,50 @@
-# 🚀 api
+<p align="center">
+  <img width="400" src="https://raw.githubusercontent.com/readmeio/api/main/docs/images/logo.svg" />
+</p>
 
-[![npm](https://img.shields.io/npm/v/api)](https://npm.im/api) [![Build](https://github.com/readmeio/api/workflows/CI/badge.svg)](https://github.com/readmeio/api)
+<p align="center">
+  Magical SDK generation from an OpenAPI definition 🪄
+</p>
 
-Automatic SDK generation from an OpenAPI definition.
+<p align="center">
+  <a href="https://npm.im/api"><img src="https://img.shields.io/npm/v/api.svg?style=for-the-badge" alt="NPM Version"></a>
+  <a href="https://npm.im/api"><img src="https://img.shields.io/node/v/api.svg?style=for-the-badge" alt="Node Version"></a>
+  <a href="https://npm.im/api"><img src="https://img.shields.io/npm/l/api.svg?style=for-the-badge" alt="MIT License"></a>
+  <a href="https://github.com/readmeio/api"><img src="https://img.shields.io/github/workflow/status/readmeio/api/CI.svg?style=for-the-badge" alt="Build status"></a>
+</p>
 
-* [Installation](#installation)
-* [Usage](#usage)
-    * [Authentication](#authentication)
-    * [Parameters and Payloads](#parameters-and-payloads)
-    * [HTTP requests](#http-requests)
-    * [Server configurations](#server-configurations)
-* [How does it work?](#how-does-it-work)
-* [Interested in contributing?](#interested-in-contributing)
-* [FAQ](#faq)
+- [Installation](https://api.readme.dev/docs/installation)
+- [Usage](https://api.readme.dev/docs/usage)
+  - [Authentication](https://api.readme.dev/docs/authentication)
+  - [Parameters and Payloads](https://api.readme.dev/docs/parameters-and-payloads)
+  - [HTTP requests](https://api.readme.dev/docs/http-requests)
+  - [Server configurations](https://api.readme.dev/docs/server-configurations)
+- [How does it work?](https://api.readme.dev/docs/how-it-works)
+- [FAQ](https://api.readme.dev/docs/faq)
 
-## Installation
-```
-npm install api --save
-```
-
-## Usage
-All you need to use `api` is to supply it an OpenAPI definition and then use the SDK as you would any other!
-
-```js
-const sdk = require('api')('https://raw.githubusercontent.com/readmeio/oas-examples/main/3.0/json/petstore.json');
-
-sdk.listPets().then(res => {
-  console.log(`My pets name is ${res[0].name}!`);
-});
-```
-
-The OpenAPI definition is automatically downloaded, cached, and transformed into a chainable [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) Promise that you can use to make API requests.
-
-### Authentication
-`api` supports API authentication through an `.auth()` method:
-
-```js
-sdk.auth('myApiToken');
-sdk.listPets().then(...);
-```
-
-With the exception of OpenID, it supports all forms of authentication supported by the OpenAPI specification! Supply `.auth()` with your auth credentials and it'll magically figure out how to use it according to the API you're using. 🧙‍♀️
-
-For example:
-
-* HTTP Basic auth: `sdk.auth('username', 'password')`
-* Bearer tokens (HTTP or OAuth 2): `sdk.auth('myBearerToken')`
-* API Keys: `sdk.auth('myApiKey')`
-
-> ℹ️ Note that `sdk.auth()` is not chainable.
+`api` is a library that facilitates creating an SDK from an OpenAPI definition. You can use its codegen offering to create an opinionated SDK for TypeScript or JS (+ TypeScript types).
 
-### Parameters and Payloads
-When supplying parameters and/or request body payloads to an API request, you don't need to explicitly define what goes where since the API definition contains all that information. All you need to do is supply either one or two objects:
-
-* `body`: This will contain all data required for a request body payload for a POST, PUT, etc. request. It can either be an array or an object — whichever you need to use the API operation you're using.
-* `metadata`: This is an object where all parameters (path, query, header, cookie) go. Again, don't worry about telling the SDK that a path parameter is for the path, that's all handled for you.
-
-For example, if you wanted to make a GET request:
-
-```js
-sdk.showPetById({ petId: 1234 }).then(...)
-```
-
-Since `petId` matches up with the `petId` path parameter, the SDK here will issue a GET request against `/pets/1234`.
-
-What about a POST request?
-
-```js
-sdk.createPets({ name: 'Buster' }).then(...)
+```sh
+$ npx api install https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.json
 ```
 
-Since `name` here would correspond on `createPets` to request body payload, this will issue a POST request against `/pets` to make a new pet named "Buster".
-
-What about operations that require both? Well you can mix them too!
-
 ```js
-sdk.updatePet({ name: 'Buster 2' }, { petId: 1234 }).then(...)
-```
-
-Since we've supplied two objects here, the SDK automatically knows that you're supplying both a `body` and `metadata`, and can make a PUT request against `/pets/1234` for you.
-
-What about a `multipart/form-data` request? That works too, and you don't even have to worry about the fun of multipart boundaries!
-
-```js
-sdk.uploadFile({ file: '/path/to/a/file.txt' }).then(...)
-```
-
-You can also give it a stream and it'll handle all of the hard work for you.
+const SDK = require('@api/petstore');
 
-```js
-sdk.uploadFile({ file: fs.createReadStream('/path/to/a/file.txt') }).then(...)
-```
-
-### HTTP requests
-If the API you're using doesn't have any documented operation IDs, you can make requests with HTTP verbs instead:
-
-```js
-sdk.get('/pets/{petId}', { petId: 1234 }).then(...)
-```
-
-The SDK supports GET, PUT, POST, DELETE, OPTIONS, HEAD, and TRACE requests.
-
-### Server configurations
-If the API you're using offers alternate server URLs and server variables in its [`servers`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#serverObject) definition you can supply this to the SDK with `.server()`:
-
-```js
-sdk.server('https://{region}.api.example.com/{basePath}', {
-  name: 'eu',
-  basePath: 'v14',
+const petstore = new SDK();
+petstore.listPets().then(res => {
+  console.log(`My pets name is ${res[0].name}!`);
 });
-
-sdk.get('/pets').then(...)
 ```
 
-When your request is executed it will be made to `https://eu.api.example.com/v14/pets`. Alternatively if you don't want to deal with URL templates you can opt to pass the full URL in instead:
+Or you can use it dynamically (though you won't have fancy TypeScript types):
 
 ```js
-sdk.server('https://eu.api.example.com/v14');
-```
-
-## How does it work?
-Behind the scenes, `api` will:
-
-1. Download the supplied OpenAPI definition, either from a publically accessible URLs or an absolute/relative path.
-2. Dereference the definition so it's easier for us to handle.
-3. Hash the definition and cache it into a directory in `node_modules/.cache/api/`.
-4. Process the definition and instantiate chainable methods for HTTP verbs and operation IDs the API contains via a JS [Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy).
-
-On subsequent requests, `api` will look in its cache, and if the supplied definition exists there, it'll retrieve it from the cache instead of re-retrieving it again.
-
-## Interested in contributing?
-Welcome! Have a look at [CONTRIBUTING.md](CONTRIBUTING.md).
-
-## FAQ
-#### Does this support YAML definitions?
-Yes! YAML definitions will be automatically converted to JSON before they're cached and loaded as an SDK.
+const petstore = require('api')(
+  'https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.json'
+);
 
-#### Does this support Swagger 2.0 definitions?
-At the moment it does not. If you wish to use an API that has a Swagger 2.0 file, you'll need to first convert it to an OpenAPI 3 definition.
-
-#### Does this support traditional OAuth 2 flows of creating tokens?
-Not yet, unfortunately. For APIs that use OAuth 2, you'll need a fully-qualified token already for `api` to make requests.
-
-#### Does this support APIs that use multiple forms of authentication on a single request?
-Not yet! This is something we're thinking about how to handle, but it's difficult with the simplified nature of the `.auth()` method as it currently does not require the user to inform the SDK of what kind of authentication scheme the token they're supplying it should match up against.
-
-#### Will this work in browsers?
-Not at the moment as the library requires some filesystem handling in order to manage its cache state, but it's something we're actively thinking about. If you'd like to help us out in making this compatible with browsers we'd love to help you out on a pull request.
-
-#### Will this validate my data before it reaches the API?
-Not yet! This is something we've got planned down the road.
-
-#### Does this support OpenAPI definitions that require authentication to download?
-Not yet! The URL that you give the module must be publicy accessible. If it isn't, you can download it to your computer/server and then use the absolute path to that file instead.
-
-```js
-const sdk = require('api')('/path/to/downloaded.json');
-```
-
-#### How do I access the Response object (for status and headers)?
-By default we parse the response based on the `content-type` header for you. You can disable this by doing the following:
-
-```js
-sdk.config({ parseResponse: false });
-```
-
-#### Where is the cache stored?
-
-By default the cache is configured with the [find-cache-dir](https://npm.im/find-cache-dir) library so the cache will be in `node_modules/.cache/api`. If placing this cache within the `node_modules/` directory is a problem for your environment (maybe you use `npm prune`) you can configure this by supplying an additional argument to the SDK instantiator:
-
-```js
-const sdk = require('api')('https://raw.githubusercontent.com/readmeio/oas-examples/main/3.0/json/petstore.json', {
-  cacheDir: './path/to/my/custom/cache/dir',
-});
-sdk.listPets().then(res => {
+petstore.listPets().then(res => {
   console.log(`My pets name is ${res[0].name}!`);
 });
 ```

package/dist/cli/codegen/languages/typescript.js

@@ -354,7 +354,7 @@ var TSGenerator = /** @class */ (function (_super) {
         var parameters = [{ name: 'path', type: 'string' }];
         var docblock = {
             description: function (writer) {
-                writer.writeLine("Access any ".concat(method, " endpoint on your API."));
+                writer.writeLine("Access any ".concat(method.toUpperCase(), " endpoint on your API."));
                 return writer;
             },
             tags: [{ tagName: 'param', text: 'path API path to make a request against.' }]
@@ -540,7 +540,7 @@ var TSGenerator = /** @class */ (function (_super) {
                 this.methodGenerics.get(operation.method).addOverload({
                     typeParameters: typeParameters,
                     parameters: [
-                        { name: 'path', type: 'string' },
+                        { name: 'path', type: "'".concat(operation.path, "'") },
                         __assign(__assign({}, parameters.body), { hasQuestionToken: false }),
                         __assign(__assign({}, parameters.metadata), { hasQuestionToken: false }),
                     ],
@@ -550,7 +550,7 @@ var TSGenerator = /** @class */ (function (_super) {
                 // Create an overload that just has a single `metadata` parameter.
                 this.methodGenerics.get(operation.method).addOverload({
                     typeParameters: typeParameters,
-                    parameters: [{ name: 'path', type: 'string' }, parameters.metadata],
+                    parameters: [{ name: 'path', type: "'".concat(operation.path, "'") }, parameters.metadata],
                     returnType: returnType,
                     docs: docblock ? [docblock] : null
                 });
@@ -558,7 +558,7 @@ var TSGenerator = /** @class */ (function (_super) {
             else {
                 this.methodGenerics.get(operation.method).addOverload({
                     typeParameters: responseTypes ? null : ['T = unknown'],
-                    parameters: __spreadArray([{ name: 'path', type: 'string' }], Object.values(parameters), true),
+                    parameters: __spreadArray([{ name: 'path', type: "'".concat(operation.path, "'") }], Object.values(parameters), true),
                     returnType: returnType,
                     docs: docblock ? [docblock] : null
                 });
@@ -629,11 +629,15 @@ var TSGenerator = /** @class */ (function (_super) {
                             Object.entries(ops).forEach(function (_a) {
                                 var method = _a[0], operation = _a[1];
                                 methods.add(method);
-                                var operationId = operation.getOperationId();
+                                var operationId = operation.getOperationId({
+                                    // This `camelCase` option will clean up any weird characters that might be present in
+                                    // the `operationId` so as we don't break TS compilation with an invalid method accessor.
+                                    camelCase: true
+                                });
                                 var params = _this.prepareParameterTypesForOperation(operation, operationId);
                                 var responses = _this.prepareResponseTypesForOperation(operation, operationId);
                                 if (operation.hasOperationId()) {
-                                    operations[operation.getOperationId()] = {
+                                    operations[operationId] = {
                                         types: {
                                             params: params,
                                             responses: responses
@@ -722,8 +726,11 @@ var TSGenerator = /** @class */ (function (_super) {
      */
     TSGenerator.prototype.prepareResponseTypesForOperation = function (operation, operationId) {
         var _this = this;
-        var schemas = operation
-            .getResponseStatusCodes()
+        var responseStatusCodes = operation.getResponseStatusCodes();
+        if (!responseStatusCodes.length) {
+            return undefined;
+        }
+        var schemas = responseStatusCodes
             .map(function (status) {
             var _a;
             var schema = operation.getResponseAsJsonSchema(status);

package/dist/core/prepareParams.js

@@ -142,7 +142,7 @@ function processFile(paramName, file) {
     }
     return Promise.reject(new TypeError(paramName
         ? "The data supplied for the `".concat(paramName, "` request body parameter is not a file handler that we support.")
-        : "The data supplied for the request body payload is not a file handler that we support."));
+        : 'The data supplied for the request body payload is not a file handler that we support.'));
 }
 /**
  * With potentially supplied body and/or metadata we need to run through them against a given API

package/dist/fetcher.d.ts

@@ -9,6 +9,7 @@ export default class Fetcher {
     static registryUUIDRegex: RegExp;
     constructor(uri: string | OASDocument);
     static isAPIRegistryUUID(uri: string): boolean;
+    static isGitHubBlobURL(uri: string): boolean;
     static getProjectPrefixFromRegistryUUID(uri: string): string;
     load(): Promise<(Omit<Omit<import("openapi-types").OpenAPIV3.Document<{}>, "paths" | "components">, "paths" | "components" | "info" | "servers" | "webhooks" | "jsonSchemaDialect"> & {
         info: import("openapi-types").OpenAPIV3_1.InfoObject;

package/dist/fetcher.js

@@ -47,10 +47,23 @@ var path_1 = __importDefault(require("path"));
 var Fetcher = /** @class */ (function () {
     function Fetcher(uri) {
         if (typeof uri === 'string') {
-            // Resolve OpenAPI definition shorthand accessors from within the ReadMe API Registry.
-            this.uri = Fetcher.isAPIRegistryUUID(uri)
-                ? uri.replace(Fetcher.registryUUIDRegex, 'https://dash.readme.com/api/v1/api-registry/$4')
-                : uri;
+            if (Fetcher.isAPIRegistryUUID(uri)) {
+                // Resolve OpenAPI definition shorthand accessors from within the ReadMe API Registry.
+                this.uri = uri.replace(Fetcher.registryUUIDRegex, 'https://dash.readme.com/api/v1/api-registry/$4');
+            }
+            else if (Fetcher.isGitHubBlobURL(uri)) {
+                /**
+                 * People may try to use a public repository URL to the source viewer on GitHub not knowing
+                 * that this page actually serves HTML. In this case we want to rewrite these to the "raw"
+                 * version of this page that'll allow us to access the API definition.
+                 *
+                 * @example https://github.com/readmeio/oas-examples/blob/main/3.1/json/petstore.json
+                 */
+                this.uri = uri.replace(/\/\/github.com/, '//raw.githubusercontent.com').replace(/\/blob\//, '/');
+            }
+            else {
+                this.uri = uri;
+            }
         }
         else {
             this.uri = uri;
@@ -59,6 +72,9 @@ var Fetcher = /** @class */ (function () {
     Fetcher.isAPIRegistryUUID = function (uri) {
         return Fetcher.registryUUIDRegex.test(uri);
     };
+    Fetcher.isGitHubBlobURL = function (uri) {
+        return /\/\/github.com\/[-_a-zA-Z0-9]+\/[-_a-zA-Z0-9]+\/blob\/(.*).(yaml|json|yml)/.test(uri);
+    };
     Fetcher.getProjectPrefixFromRegistryUUID = function (uri) {
         var matches = uri.match(Fetcher.registryUUIDRegex);
         if (!matches) {

package/dist/packageInfo.d.ts

@@ -1,2 +1,2 @@
 export declare const PACKAGE_NAME = "api";
-export declare const PACKAGE_VERSION = "5.0.0-beta.1";
+export declare const PACKAGE_VERSION = "5.0.0-beta.2";

package/dist/packageInfo.js

@@ -3,4 +3,4 @@ exports.__esModule = true;
 exports.PACKAGE_VERSION = exports.PACKAGE_NAME = void 0;
 // This file is automatically updated by the build script.
 exports.PACKAGE_NAME = 'api';
-exports.PACKAGE_VERSION = '5.0.0-beta.1';
+exports.PACKAGE_VERSION = '5.0.0-beta.2';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "api",
-  "version": "5.0.0-beta.1",
-  "description": "Generate an SDK from an OpenAPI definition",
+  "version": "5.0.0-beta.2",
+  "description": "Magical SDK generation from an OpenAPI definition 🪄",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
@@ -10,12 +10,9 @@
   "scripts": {
     "build": "tsc",
     "debug:bin": "node -r ts-node/register src/bin.ts",
-    "lint": "eslint . --ext .js,.ts",
     "prebuild": "rm -rf dist/; npm run prebuild.packageConfig",
-    "prebuild.packageConfig": "node -p \"'// This file is automatically updated by the build script.\\nexport const PACKAGE_NAME = \\'' + require('./package.json').name + '\\';\\nexport const PACKAGE_VERSION = \\'' + require('./package.json').version + '\\';'\" > src/packageInfo.ts",
+    "prebuild.packageConfig": "node -p \"'// This file is automatically updated by the build script.\\nexport const PACKAGE_NAME = \\'' + require('./package.json').name + '\\';\\nexport const PACKAGE_VERSION = \\'' + require('./package.json').version + '\\';'\" > src/packageInfo.ts; git add src/packageInfo.ts",
     "prepack": "npm run build",
-    "pretest": "npm run lint",
-    "prettier": "prettier --list-different --write \"./**/**.{js,ts}\"",
     "test": "nyc mocha \"test/**/*.test.ts\""
   },
   "repository": {
@@ -23,7 +20,7 @@
     "url": "https://github.com/readmeio/api.git",
     "directory": "packages/api"
   },
-  "homepage": "https://github.com/readmeio/api",
+  "homepage": "https://api.readme.dev",
   "bugs": {
     "url": "https://github.com/readmeio/api/issues"
   },
@@ -32,6 +29,12 @@
   "engines": {
     "node": ">=14"
   },
+  "keywords": [
+    "api",
+    "openapi",
+    "sdk",
+    "swagger"
+  ],
   "dependencies": {
     "@readme/oas-to-har": "^17.0.8",
     "@readme/openapi-parser": "^2.2.0",
@@ -60,7 +63,6 @@
     "validate-npm-package-name": "^4.0.0"
   },
   "devDependencies": {
-    "@readme/eslint-config": "^8.7.3",
     "@readme/oas-examples": "^5.4.1",
     "@types/chai": "^4.3.1",
     "@types/find-cache-dir": "^3.2.1",
@@ -73,15 +75,13 @@
     "@types/ssri": "^7.1.1",
     "@types/validate-npm-package-name": "^4.0.0",
     "chai": "^4.3.6",
-    "eslint": "^8.14.0",
     "fetch-mock": "^9.11.0",
     "mocha": "^10.0.0",
     "mock-require": "^3.0.3",
     "nyc": "^15.1.0",
-    "prettier": "^2.6.2",
     "sinon": "^14.0.0",
     "sinon-chai": "^3.7.0",
-    "typescript": "^4.6.4",
+    "typescript": "^4.7.4",
     "unique-temp-dir": "^1.0.0"
   },
   "prettier": "@readme/eslint-config/prettier",
@@ -91,5 +91,5 @@
       "test/"
     ]
   },
-  "gitHead": "5970a1f16a6444733f53da28f6d01c5d544372c3"
+  "gitHead": "aa738b1bf46b447afed38507d3fc49acbbad6309"
 }

package/src/cli/codegen/languages/typescript.ts

@@ -373,7 +373,7 @@ sdk.server('https://eu.api.example.com/v14');`)
     const parameters: OptionalKind<ParameterDeclarationStructure>[] = [{ name: 'path', type: 'string' }];
     const docblock: OptionalKind<JSDocStructure> = {
       description: writer => {
-        writer.writeLine(`Access any ${method} endpoint on your API.`);
+        writer.writeLine(`Access any ${method.toUpperCase()} endpoint on your API.`);
         return writer;
       },
       tags: [{ tagName: 'param', text: 'path API path to make a request against.' }],
@@ -589,7 +589,7 @@ sdk.server('https://eu.api.example.com/v14');`)
         this.methodGenerics.get(operation.method).addOverload({
           typeParameters,
           parameters: [
-            { name: 'path', type: 'string' },
+            { name: 'path', type: `'${operation.path}'` },
             { ...parameters.body, hasQuestionToken: false },
             { ...parameters.metadata, hasQuestionToken: false },
           ],
@@ -600,14 +600,14 @@ sdk.server('https://eu.api.example.com/v14');`)
         // Create an overload that just has a single `metadata` parameter.
         this.methodGenerics.get(operation.method).addOverload({
           typeParameters,
-          parameters: [{ name: 'path', type: 'string' }, parameters.metadata],
+          parameters: [{ name: 'path', type: `'${operation.path}'` }, parameters.metadata],
           returnType,
           docs: docblock ? [docblock] : null,
         });
       } else {
         this.methodGenerics.get(operation.method).addOverload({
           typeParameters: responseTypes ? null : ['T = unknown'],
-          parameters: [{ name: 'path', type: 'string' }, ...Object.values(parameters)],
+          parameters: [{ name: 'path', type: `'${operation.path}'` }, ...Object.values(parameters)],
           returnType,
           docs: docblock ? [docblock] : null,
         });
@@ -673,12 +673,17 @@ sdk.server('https://eu.api.example.com/v14');`)
       Object.entries(ops).forEach(([method, operation]: [HttpMethods, Operation]) => {
         methods.add(method);
 
-        const operationId = operation.getOperationId();
+        const operationId = operation.getOperationId({
+          // This `camelCase` option will clean up any weird characters that might be present in
+          // the `operationId` so as we don't break TS compilation with an invalid method accessor.
+          camelCase: true,
+        });
+
         const params = this.prepareParameterTypesForOperation(operation, operationId);
         const responses = this.prepareResponseTypesForOperation(operation, operationId);
 
         if (operation.hasOperationId()) {
-          operations[operation.getOperationId()] = {
+          operations[operationId] = {
             types: {
               params,
               responses,
@@ -758,8 +763,12 @@ sdk.server('https://eu.api.example.com/v14');`)
    * @param operationId
    */
   prepareResponseTypesForOperation(operation: Operation, operationId: string) {
-    const schemas = operation
-      .getResponseStatusCodes()
+    const responseStatusCodes = operation.getResponseStatusCodes();
+    if (!responseStatusCodes.length) {
+      return undefined;
+    }
+
+    const schemas = responseStatusCodes
       .map(status => {
         const schema = operation.getResponseAsJsonSchema(status);
         if (!schema) {

package/src/core/prepareParams.ts

@@ -22,7 +22,7 @@ import getJSONSchemaDefaults from './getJSONSchemaDefaults';
 function digestParameters(parameters: ParameterObject[]): Record<string, ParameterObject> {
   return parameters.reduce((prev, param) => {
     if ('$ref' in param || 'allOf' in param || 'anyOf' in param || 'oneOf' in param) {
-      throw new Error(`The OpenAPI document for this operation wasn't dereferenced before processing.`);
+      throw new Error("The OpenAPI document for this operation wasn't dereferenced before processing.");
     } else if (param.name in prev) {
       throw new Error(
         `The operation you are using has the same parameter, ${param.name}, spread across multiple entry points. We unfortunately can't handle this right now.`
@@ -123,7 +123,7 @@ function processFile(
     new TypeError(
       paramName
         ? `The data supplied for the \`${paramName}\` request body parameter is not a file handler that we support.`
-        : `The data supplied for the request body payload is not a file handler that we support.`
+        : 'The data supplied for the request body payload is not a file handler that we support.'
     )
   );
 }

package/src/fetcher.ts

@@ -18,10 +18,21 @@ export default class Fetcher {
 
   constructor(uri: string | OASDocument) {
     if (typeof uri === 'string') {
-      // Resolve OpenAPI definition shorthand accessors from within the ReadMe API Registry.
-      this.uri = Fetcher.isAPIRegistryUUID(uri)
-        ? uri.replace(Fetcher.registryUUIDRegex, 'https://dash.readme.com/api/v1/api-registry/$4')
-        : uri;
+      if (Fetcher.isAPIRegistryUUID(uri)) {
+        // Resolve OpenAPI definition shorthand accessors from within the ReadMe API Registry.
+        this.uri = uri.replace(Fetcher.registryUUIDRegex, 'https://dash.readme.com/api/v1/api-registry/$4');
+      } else if (Fetcher.isGitHubBlobURL(uri)) {
+        /**
+         * People may try to use a public repository URL to the source viewer on GitHub not knowing
+         * that this page actually serves HTML. In this case we want to rewrite these to the "raw"
+         * version of this page that'll allow us to access the API definition.
+         *
+         * @example https://github.com/readmeio/oas-examples/blob/main/3.1/json/petstore.json
+         */
+        this.uri = uri.replace(/\/\/github.com/, '//raw.githubusercontent.com').replace(/\/blob\//, '/');
+      } else {
+        this.uri = uri;
+      }
     } else {
       this.uri = uri;
     }
@@ -31,6 +42,10 @@ export default class Fetcher {
     return Fetcher.registryUUIDRegex.test(uri);
   }
 
+  static isGitHubBlobURL(uri: string) {
+    return /\/\/github.com\/[-_a-zA-Z0-9]+\/[-_a-zA-Z0-9]+\/blob\/(.*).(yaml|json|yml)/.test(uri);
+  }
+
   static getProjectPrefixFromRegistryUUID(uri: string) {
     const matches = uri.match(Fetcher.registryUUIDRegex);
     if (!matches) {

package/src/packageInfo.ts

@@ -1,3 +1,3 @@
 // This file is automatically updated by the build script.
 export const PACKAGE_NAME = 'api';
-export const PACKAGE_VERSION = '5.0.0-beta.1';
+export const PACKAGE_VERSION = '5.0.0-beta.2';