feat(openapi): introduction of a new openapi:inspect command (#698)

* feat: introduction of a new `openapi:uses` command * fix: clarifying that our openapi commands accept urls * feat: swapping out the analysis work with it now living in `oas` * fix: updating oas to move the reducer back to where it was * feat: adding `--feature` args to `openapi:uses` * feat: improvements to readme and circularRef reporting * test: adding tests * fix: fixing spacing bugs and adding tests * fix: check for features length * Update src/lib/softError.ts Co-authored-by: Kanad Gupta <[email protected]> * Update src/cmds/openapi/uses.ts Co-authored-by: Kanad Gupta <[email protected]> * fix: pr feedback * fix: renaming the command to `openapi:uses` * docs: `openapi:inspect` (#706) * fix: file placeholders * docs: add docs on inspect Co-authored-by: Kanad Gupta <[email protected]> Co-authored-by: Kanad Gupta <[email protected]>
readmeio · Dec 8, 2022 · daa5346 · daa5346
1 parent 526e716
commit daa5346
Show file tree

Hide file tree

Showing 21 changed files with 1,525 additions and 342 deletions.
diff --git a/README.md b/README.md
@@ -140,12 +140,13 @@ With `rdme`, you have access to a variety of tools to manage your API definition
 - [Syncing](#syncing-an-api-definition-to-readme) 🦉
 - [Validation](#validating-an-api-definition) ✅
 - [Reduction](#reducing-an-api-definition) 📉
+- [Inspection](#inspecting-an-api-definition) 🔍
 
 `rdme` supports [OpenAPI 3.1](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md), [OpenAPI 3.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md), and [Swagger 2.x](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md).
 
 <!--alex ignore postman-postwoman-->
 
-You can also pass in [Postman Collections](https://www.postman.com/collection/). Postman Collections are converted to OpenAPI using [`postman-to-openapi`](https://github.com/joolfe/postman-to-openapi) prior to any syncing/validation/reduction.
+You can also pass in [Postman Collections](https://www.postman.com/collection/). Postman Collections are converted to OpenAPI using [`postman-to-openapi`](https://github.com/joolfe/postman-to-openapi) prior to any syncing/validation/etc.
 
 The following examples use JSON files, but `rdme` supports API Definitions that are written in either JSON or YAML.
 
@@ -175,32 +176,32 @@ rdme openapi
 
 ##### Uploading a New API Definition to ReadMe
 
-This will upload `path-to-openapi.json` to your project and return an ID and URL for you to later update your file, and view it in the client.
+This will upload the API definition at the given URL or path to your project and return an ID and URL for you to later update your file, and view it in the client.
 
 ```sh
-rdme openapi [path-to-file.json]
+rdme openapi [url-or-local-path-to-file]
 ```
 
 If you want to bypass the prompt to create or update an API definition, you can pass the `--create` flag:
 
 ```sh
-rdme openapi [path-to-file.json] --version={project-version} --create
+rdme openapi [url-or-local-path-to-file] --version={project-version} --create
 ```
 
 ##### Editing (Re-Syncing) an Existing API Definition
 
 This will edit (re-sync) an existing API definition (identified by `--id`) within your ReadMe project. **This is the recommended approach for usage in CI environments.**
 
 ```sh
-rdme openapi [path-to-file.json] --id={existing-id}
+rdme openapi [url-or-local-path-to-file] --id={existing-id}
 ```
 
 ##### Uploading or Editing an API Definition in a Project Version
 
 You can additionally include a version flag, specifying the target version for your file's destination. This approach will provide you with CLI prompts, so we do not recommend this technique in CI environments.
 
 ```sh
-rdme openapi [path-to-file.json] --version={project-version}
+rdme openapi [url-or-local-path-to-file] --version={project-version}
 ```
 
 If you wish to use the version specified [in the `info.version` field of your API definition](https://spec.openapis.org/oas/v3.1.0#fixed-fields-0), you can pass the `--useSpecVersion` option. For example, say [the `info` object](https://spec.openapis.org/oas/v3.1.0#info-object) of your API definition looks like this:
@@ -216,13 +217,13 @@ If you wish to use the version specified [in the `info.version` field of your AP
 You can pass in the `--useSpecVersion` option, which would be equivalent to passing in `--version=1.2.3`:
 
 ```sh
-rdme openapi [path-to-file.json] --useSpecVersion
+rdme openapi [url-or-local-path-to-file] --useSpecVersion
 ```
 
 You can add `--update` to the command so if there's only one API definition for the given project version to update, it will select it without any prompts:
 
 ```sh
-rdme openapi [path-to-file.json] --version={project-version} --update
+rdme openapi [url-or-local-path-to-file] --version={project-version} --update
 ```
 
 ##### Override the Working Directory
@@ -238,7 +239,7 @@ rdme openapi petstore.json --workingDirectory=[path to directory]
 You can also perform a local validation of your API definition (no ReadMe account required!), which can be useful when constructing or editing your API definition.
 
 ```sh
-rdme openapi:validate [path-to-file.json]
+rdme openapi:validate [url-or-local-path-to-file]
 ```
 
 Similar to the `openapi` command, you can also [omit the file path](#omitting-the-file-path).
@@ -248,7 +249,7 @@ Similar to the `openapi` command, you can also [omit the file path](#omitting-th
 We also offer a tool that allows you to reduce a large API definition down to a specific set of tags or paths (again, no ReadMe account required!). This can be useful if you're debugging a problematic schema somewhere, or if you have a file that is too big to maintain.
 
 ```sh
-rdme openapi:reduce [path-to-file.json]
+rdme openapi:reduce [url-or-local-path-to-file]
 ```
 
 The command will ask you a couple questions about how you wish to reduce the file and then do so. If you wish to automate this command, you can pass in CLI arguments to bypass the prompts. Here's an example use case:
@@ -265,6 +266,22 @@ rdme openapi:reduce petstore.json --path /pet/{id} --method get --method put --o
 
 As with the `openapi` command, you can also [omit the file path](#omitting-the-file-path).
 
+#### Inspecting an API Definition
+
+This tool can also perform a comprehensive analysis (again, no ReadMe account required!) of your API definition to determine how it's utilizing aspects of [the OpenAPI Specification](https://spec.openapis.org/oas/v3.1.0.html) (such as circular references, polymorphism, etc.) and any [ReadMe-specific extensions](https://docs.readme.com/main/docs/openapi-extensions) you might be using.
+
+```sh
+rdme openapi:inspect [url-or-local-path-to-file]
+```
+
+This command contains a `--feature` flag so you can filter for one or several specific features. If you pass in one or more `--feature` flags, the command returns a `0` exit code if your definition contains all of the given features and a `1` exit code if your definition lacks any of the given features.
+
+```sh
+rdme openapi:inspect [url-or-local-path-to-file] --feature circularRefs --feature polymorphism
+```
+
+As with the `openapi` command, you can also [omit the file path](#omitting-the-file-path).
+
 ### Docs (a.k.a. Guides) 📖
 
 The Markdown files will require YAML front matter with certain ReadMe documentation attributes. Check out [our docs](https://docs.readme.com/docs/rdme#markdown-file-setup) for more info on setting up your front matter.

diff --git a/__tests__/__snapshots__/index.test.ts.snap b/__tests__/__snapshots__/index.test.ts.snap
@@ -6,7 +6,7 @@ Upload, or resync, your OpenAPI/Swagger definition to ReadMe.
 
 Usage
 
-  rdme openapi [file] [options] 
+  rdme openapi [file|url] [options] 
 
 Options
 
@@ -30,8 +30,10 @@ Options
 
 Related commands
 
-  $ rdme openapi:reduce     Reduce an OpenAPI definition into a smaller subset. 
-  $ rdme openapi:validate   Validate your OpenAPI/Swagger definition.           
+  $ rdme openapi:reduce     Reduce an OpenAPI definition into a smaller subset.                     
+  $ rdme openapi:validate   Validate your OpenAPI/Swagger definition.                               
+  $ rdme openapi:inspect    Analyze an OpenAPI/Swagger definition for various OpenAPI and ReadMe    
+                            feature usage.                                                          
 "
 `;
 
@@ -41,7 +43,7 @@ Upload, or resync, your OpenAPI/Swagger definition to ReadMe.
 
 Usage
 
-  rdme openapi [file] [options] 
+  rdme openapi [file|url] [options] 
 
 Options
 
@@ -65,8 +67,10 @@ Options
 
 Related commands
 
-  $ rdme openapi:reduce     Reduce an OpenAPI definition into a smaller subset. 
-  $ rdme openapi:validate   Validate your OpenAPI/Swagger definition.           
+  $ rdme openapi:reduce     Reduce an OpenAPI definition into a smaller subset.                     
+  $ rdme openapi:validate   Validate your OpenAPI/Swagger definition.                               
+  $ rdme openapi:inspect    Analyze an OpenAPI/Swagger definition for various OpenAPI and ReadMe    
+                            feature usage.                                                          
 "
 `;
 
@@ -76,7 +80,7 @@ Upload, or resync, your OpenAPI/Swagger definition to ReadMe.
 
 Usage
 
-  rdme openapi [file] [options] 
+  rdme openapi [file|url] [options] 
 
 Options
 
@@ -100,8 +104,10 @@ Options
 
 Related commands
 
-  $ rdme openapi:reduce     Reduce an OpenAPI definition into a smaller subset. 
-  $ rdme openapi:validate   Validate your OpenAPI/Swagger definition.           
+  $ rdme openapi:reduce     Reduce an OpenAPI definition into a smaller subset.                     
+  $ rdme openapi:validate   Validate your OpenAPI/Swagger definition.                               
+  $ rdme openapi:inspect    Analyze an OpenAPI/Swagger definition for various OpenAPI and ReadMe    
+                            feature usage.                                                          
 "
 `;