oas 19.0.3 → 20.0.0

package/.alexignore

@@ -0,0 +1 @@
+CHANGELOG.md

package/.alexrc

@@ -0,0 +1,3 @@
+{
+  "profanitySureness": 1
+}

package/CHANGELOG.md

@@ -1,3 +1,21 @@
+## 20.0.0 (2022-10-28)
+
+> **BREAKING CHANGE**
+>
+> This library is shifting focus to being soley focused on OpenAPI tooling and longer ships a CLI wrapper for creating OpenAPI definitions. If you need an OpenAPI (or Swagger) definition for your API we recommend checking out the API editing experience within [ReadMe](https://readme.com), manually maintaining JSON/YAML files (it sounds worse than it actually is), or the language-agnostic [swagger-inline](https://npm.im/swagger-inline).
+
+* chore(deps-dev): bumping dev deps ([371e041](https://github.com/readmeio/oas/commit/371e041))
+* feat: sunsetting the cli (#702) ([c1b2728](https://github.com/readmeio/oas/commit/c1b2728)), closes [#702](https://github.com/readmeio/oas/issues/702)
+* docs: adding a hero image for the readme ([26d6018](https://github.com/readmeio/oas/commit/26d6018))
+
+
+
+## <small>19.0.4 (2022-10-27)</small>
+
+* fix: edgecase where we wouldn't always create valid operationIds (#701) ([df160c2](https://github.com/readmeio/oas/commit/df160c2)), closes [#701](https://github.com/readmeio/oas/issues/701)
+
+
+
 ## <small>19.0.3 (2022-10-27)</small>
 
 * fix: various compatibility issues with `api` codegen (#700) ([01a6554](https://github.com/readmeio/oas/commit/01a6554)), closes [#700](https://github.com/readmeio/oas/issues/700)

package/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 ReadMe
+Copyright (c) 2022 ReadMe
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,10 +1,43 @@
-# oas
-
-Working with OpenAPI definitions is hard. This makes it easier.
-
-[![Build](https://github.com/readmeio/oas/workflows/CI/badge.svg)](https://github.com/readmeio/oas/) [![](https://img.shields.io/npm/v/oas)](https://npm.im/oas)
-
-[![](https://d3vv6lp55qjaqc.cloudfront.net/items/1M3C3j0I0s0j3T362344/Untitled-2.png)](https://readme.com)
+<p align="center">
+  <a href="https://npm.im/oas">
+    <img src="https://raw.githubusercontent.com/readmeio/oas/main/.github/hero.png" alt="oas" />
+  </a>
+</p>
+
+<p align="center">
+  Comprehensive tooling for working with OpenAPI definitions
+</p>
+
+<p align="center">
+  <a href="https://npm.im/oas"><img src="https://img.shields.io/npm/v/oas.svg?style=for-the-badge" alt="NPM Version"></a>
+  <a href="https://npm.im/oas"><img src="https://img.shields.io/node/v/oas.svg?style=for-the-badge" alt="Node Version"></a>
+  <a href="https://npm.im/oas"><img src="https://img.shields.io/npm/l/oas.svg?style=for-the-badge" alt="MIT License"></a>
+  <a href="https://github.com/readmeio/oas"><img src="https://img.shields.io/github/workflow/status/readmeio/oas/CI.svg?style=for-the-badge" alt="Build status"></a>
+</p>
+
+`oas` is the library that we've built at [ReadMe](https://readme.com) for powering everything we do related to [OpenAPI](https://www.openapis.org/); from our [Reference Guides](https://readme.com/documentation), to our [Metrics product](https://readme.com/metrics) or to other in-house tooling like [code generation](https://npm.im/@readme/oas-to-snippet), [request execution](https://npm.im/@readme/oas-to-har), and [SDK code generation](https://api.readme.dev/).
+
+---
+
+- [Installation](https://api.readme.dev/docs/installation)
+- [Usage](#usage)
+  - [OpenAPI definitions](#openapi-definitions)
+    - [General](#general)
+    - [Operations](#operations)
+    - [Servers](#servers)
+    - [Specification Extensions](#specification-extensions)
+    - [User Authentication](#user-authentication)
+  - [Operations](#operations-1)
+    - [General](#general-1)
+    - [Callbacks](#callbacks)
+    - [Request Body](#request-body)
+    - [Responses](#responses)
+    - [Security](#security)
+    - [Specification Extensions](#specification-extensions-1)
+  - [Callbacks](#callbacks)
+    - [General](#general-2)
+  - [Webhooks](#webhooks)
+- [FAQ](#faq)
 
 ## Installation
 
@@ -12,62 +45,201 @@ Working with OpenAPI definitions is hard. This makes it easier.
 npm install oas
 ```
 
-## CLI
-The CLI tool makes creating API definition files easier. It currently supports [OpenAPI 3.x](https://swagger.io/specification/) and [Swagger 2.0](https://swagger.io/specification/v2/) documents.
+## Usage
 
-### Usage
+> **Note**
+> If you need to use this library within a browser you'll likely need to use a bundler like [Webpack](https://webpack.js.org/) or [Rollup](https://rollupjs.org/).
 
-Go to a directory with your API, and type:
+`oas` offers a main `Oas` class, which will be your main entrypoint for using the library.
 
-```
-oas init
+```js
+import Oas from 'oas';
+import petstoreSpec from '@readme/oas-examples/3.0/json/petstore.json';
+
+const petstore = new Oas(petstoreSpec);
 ```
 
-It will walk you through how to document your API with a OpenAPI 3.0 Spec.
+Here the `Oas` constructor takes a JSON API definition (`petstoreSpec`). All API definitions you feed it must be JSON and must be an OpenAPI definition. If you have a YAML or Swagger definition you will need to convert it (our [oas-normalize](https://npm.im/oas-normalize) library can do this for you). And if you're in a CJS or non-`import` environment you can pull the library in with `require('oas').default`.
 
-#### Commands
+From here, the following APIs are at your disposal.
 
-```
-Usage: oas <command>
+### OpenAPI definitions
 
-  $ oas init                    Create a new OpenAPI definition
-  $ oas help                    Learn what you can do with oas
-  $ oas endpoint                Learn how to document an endpoint
-  $ oas generate [oas.json]     Output your OpenAPI definition (use --pretty for colors)
-  $ oas validate [oas.json]     Validate your OpenAPI definition
-```
+Because this library has full TypeScript types and docblocks this README is not intended to be full documentation so consult the individual method docblocks if you need more information on a specific method.
 
-### Swagger Inline
+#### General
 
-`oas` uses [swagger-inline](https://github.com/readmeio/swagger-inline) which allows you include a little OpenAPI snippet in a comment above your code, and collects them all together into one OpenAPI file:
+<!-- prettier-ignore-start -->
+| Method | Description |
+| :--- | :--- |
+| `#dereference()` | Dereference the current OpenAPI definition. Note that this will ignore circular references. |
+| `#getDefinition()` | Retrieve the OpenAPI definition that was fed into the `Oas` constructor. |
+| `#getTags()` | Retrieve an array of all tags that exist within the API definition and are set on operations. |
+| `#getPaths()` | Retrieve every operation that exists within the API definition. This returns an array of instances of the `Operation` class. |
+| `#getVersion()` | Retrieve the OpenAPI version that this API definition is targeted for. |
+| `#getWebhooks()` | Retrieve every webhook operation that exists within the API definition. This returns an array of instances of the `Webhook` class. |
+| `#init()` | An alternative for `new Oas()` that you can use if the typing on the `Oas` constructor gives you trouble. Typing OpenAPI definitions is hard! |
+<!-- prettier-ignore-end -->
 
-```js
-/*
- * @oas [get] /pet/{petId}
- * description: "Returns all pets from the system that the user has access to"
- * parameters:
- *   - (path) petId=hi* {String} The pet ID
- *   - (query) limit {Integer:int32} The number of resources to return
-*/
-route.get("/pet/:petId", pet.show);
-```
+#### Operations
 
-You need to start with `@oas [method] path`, but everything below it is a valid [Path Definition](http://swagger.io/specification/#pathItemObject).
+<!-- prettier-ignore-start -->
+| Method | Description |
+| :--- | :--- |
+| `#findOperation()` | Discover an operation with the current OpenAPI definition that matches a given URL and HTTP method. |
+| `#findOperationWithoutMethod()` | Like `oas.findOperation()` but without supplying an HTTP method. |
+| `#getOperation()` | Same as `oas.findOperation()` but this returns an instance of the `Operation` class. |
+| `#operation()` | Retrieve an instance of the `Operation` or `Webhook` classes for a given path and HTTP method. |
+<!-- prettier-ignore-end -->
 
-You can also do **inline parameters**, which are shorthand for parameters. They aren't valid OpenAPI properties but `swagger-inline` knows how to compile them:
+#### Servers
 
-```
-- (in) name=default* {type:format} Description
-```
+<!-- prettier-ignore-start -->
+| Method | Description |
+| :--- | :--- |
+| `#defaultVariables()` | Retrieve the default server variables for a specific server URL, while also potentially factoring in user data. You can specify user variable data to the `Oas` constructor. Check out [Using Variables in Documentation](https://docs.readme.com/docs/user-data-options#using-variables-in-documentation) for some background on how we use this. |
+| `#replaceUrl()` | Replace a given templated server URL with supplied server variable data. |
+| `#splitUrl()` | Chunk out a specific server URL into its individual parts. |
+| `#splitVariables` | Chunk out a given URL and if it matches a server URL in the OpenAPI file, extract the matched server variables that are present in the URL. |
+| `#url()` | Retrive a fully composed server URL. You can optionally select which of the defined server URLs to use as well as specify server variable information. |
+| `#variables()` | Retrieve all server variables that a specific server URL in the definition has. |
+<!-- prettier-ignore-end -->
+
+#### Specification Extensions
+
+<!-- prettier-ignore-start -->
+| Method | Description |
+| :--- | :--- |
+| `#getExtension()` | Retrieve a given [specification extension](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions) if it exists at the root of the API definition. |
+| `#hasExtension()` | Determine if a given [specification extension](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions) exists on the root of the API definition.   |
+<!-- prettier-ignore-end -->
+
+#### User Authentication
+
+<!-- prettier-ignore-start -->
+| Method | Description |
+| :--- | :--- |
+| `#getAuth()` | Retrieve the appropriate API keys for the current OpenAPI definition from an object of user data. Check out [Using Variables in Documentation](https://docs.readme.com/docs/user-data-options#using-variables-in-documentation) for some background on how we use this. |
+<!-- prettier-ignore-end -->
 
-## Tooling
-This library also exposes a set of tooling to help you manage OpenAPI definitions. You can access it by loading:
+---
+
+### Operations
+
+For your convenience, the entrypoint into the `Operation` class should generally always be through `Oas.operation()`. For example:
 
 ```js
 import Oas from 'oas';
-// or: const Oas = require('oas').default;
-```
+import petstoreSpec from '@readme/oas-examples/3.0/json/petstore.json';
 
-Also exposed within the main `oas` export is an `Operation` class that can help you manage and retrieve specific data from an API operation.
+const petstore = new Oas(petstoreSpec);
+const operation = petstore.operation('/pet', 'post');
+```
 
-> If you need to use this library within a browser you'll likely need to use a bundler like [Webpack](https://webpack.js.org/) or [Rollup](https://rollupjs.org/).
+#### General
+
+<!-- prettier-ignore-start -->
+| Method | Description |
+| :--- | :--- |
+| `#getContentType()` | Retrieve the primary request body content type. If multiple are present, prefer whichever is JSON-compliant. |
+| `#getDescription()` | Retrieve the `description` that's set on this operation. This supports common descriptions that may be set at the [path item level](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject). |
+| `#getOperationId()` | Retrieve the `operationId` that's present on the operation, and if one is not present one will be created based off the method + path and returned instead. |
+| `#hasOperationId()` | Determine if the operation has an `operationId` present. |
+| `#isDeprecated()` | Determine if this operation is marked as deprecated. |
+| `#isFormUrlEncoded()` | Determine if this operation requires its payload to be delivered as `application/x-www-form-urlencoded`. |
+| `#isJson()` | Determine if this operation requires its payload to be delivered as JSON. |
+| `#isMultipart()` | Determine if this operation requires its data to be sent as a multipart payload. |
+| `#isXml()` | Determine if this operation requires its data to be sent as XML. |
+| `#getHeaders()` | Retrieve all headers that can either be sent for or returned from this operation. This includes header-based authentication schemes, common header parameters, and request body and response content types. |
+| `#getSummary()` | Retrieve the `summary` that's set on this operation. This supports common summaries that may be set at the [path item level](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject). |
+| `#getTags()` | Retrieve all tags, and [their metadata](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#tagObject), that exist on this operation. |
+<!-- prettier-ignore-end -->
+
+#### Callbacks
+
+<!-- prettier-ignore-start -->
+| Method | Description |
+| :--- | :--- |
+| `#getCallback()` | Retrieve a specific callback on this operation. This will return an instance of the `Callback` class. |
+| `#getCallbackExamples()` | Retrieve an array of all calback examples that this operation has defined. |
+| `#getCallbacks()` | Retrieve all callbacks that this operation has. Similar to `Oas.getPaths()` returning an array of `Operation` instances this will return an array of `Callback` instances. |
+| `#hasCallbacks()` | Determine if this operation has any callbacks defined. |
+<!-- prettier-ignore-end -->
+
+#### Parameters
+
+> **Note**
+> All parameter accessors here support, and will automatically retrieve and handle, common parameters that may be set at the [path item level](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject).
+
+<!-- prettier-ignore-start -->
+| Method | Description |
+| :--- | :--- |
+| `#getParameters()` | Retrieve all parameters that may be used with on this operation. |
+| `#getParametersAsJSONSchema()` | Retrieve and convert the operations parameters into an array of JSON Schema schemas for each available type of parameter available on the operation: `path`, `query`, `body`, `cookie`, `formData`, and `header`. |
+| `#hasParameters()` | Determine if the operation has any parameters to send. |
+| `#hasRequiredParameters()` | Determine if any of the parameters on this operation are required. |
+<!-- prettier-ignore-end -->
+
+#### Request Body
+
+<!-- prettier-ignore-start -->
+| Method | Description |
+| :--- | :--- |
+| `#getRequestBody()` | Retrieve the raw request body object for a given content type. If none is specified it will return either the first that's JSON-like, or the first defined. |
+| `#getRequestBodyExamples()` | Retrieve an array of all request body examples that this operation has defined. |
+| `#getRequestBodyMediaTypes()` | Retrieve a list of all the media/content types that the operation can accept a request body payload for. |
+| `#hasRequestBody()` | Determine if this operation has a request body defined. |
+<!-- prettier-ignore-end -->
+
+#### Responses
+
+<!-- prettier-ignore-start -->
+| Method | Description |
+| :--- | :--- |
+| `#getResponseAsJSONSchema()` | Retrive and convert a response on this operation into JSON Schema. |
+| `#getResponseByStatusCode()` | Retrieve the raw response object for a given status code. |
+| `#getResponseExamples()` | Retrieve an array of all response examples that this operation has defined. |
+| `#getResponseStatusCodes()` | Retrieve all status codes that this operation may respond with. |
+| `#hasRequiredRequestBody()` | Determine if this operation has a required request body. |
+<!-- prettier-ignore-end -->
+
+#### Security
+
+<!-- prettier-ignore-start -->
+| Method | Description |
+| :--- | :--- |
+| `#getSecurity()` | Return all security requirements that are applicable for either this operation, or if the operation has none specific to it, then for the entire API. |
+| `#getSecurityWithTypes()` | Return a collection of all security schemes applicable to this operation (using `#getSecurity()`), grouped by how the security should be handled (either AND or OR auth requirements). |
+| `#prepareSecurity` | Return an object of every security scheme that _can_ be used on this operation, indexed by the type of security scheme it is (eg. `Basic`, `OAuth2`, `APIKey`, etc.). |
+<!-- prettier-ignore-end -->
+
+#### Specification Extensions
+
+<!-- prettier-ignore-start -->
+| Method | Description |
+| :--- | :--- |
+| `#getExtension()` | Retrieve a given [specification extension](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions) if it exists on this operation. |
+| `#hasExtension()` | Determine if a given [specification extension](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions) exists on this operation. |
+<!-- prettier-ignore-end -->
+
+### Callbacks
+
+The `Callback` class inherits `Operation` so every API available on instances of `Operation` is available here too. Much like `Operation`, we also support common parameters, summaries, and descriptions that may be set at the [path item level](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject) within a `callbacks` definition.
+
+#### General
+
+<!-- prettier-ignore-start -->
+| Method | Description |
+| :--- | :--- |
+| `#getIdentifier()` | Retrieve the primary identifier of this callback. |
+<!-- prettier-ignore-end -->
+
+### Webhooks
+
+Because our `Webhook` class extends `Operation`, every API that's available on the [Operation](#operation) class is available on webhooks.
+
+## FAQ
+
+#### Can I create an OpenAPI definition with this?
+
+Though `oas` used to offer functionality related to this, it does no longer. If you need an OpenAPI (or Swagger) definition for your API we recommend checking out the API editing experience within [ReadMe](https://readme.com), manually maintaining JSON/YAML files (it sounds worse than it actually is), or the language-agnostic [swagger-inline](https://npm.im/swagger-inline).

package/dist/index.d.ts

@@ -184,7 +184,7 @@ export default class Oas {
     getPaths(): Record<string, Record<RMOAS.HttpMethods, Operation | Webhook>>;
     /**
      * Returns the `webhooks` object that exists in this API definition but with every `method`
-     * mapped to an instance of the `Operation` class.
+     * mapped to an instance of the `Webhook` class.
      *
      * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#oasObject}
      * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#openapi-object}

package/dist/index.js

@@ -656,7 +656,7 @@ var Oas = /** @class */ (function () {
     };
     /**
      * Returns the `webhooks` object that exists in this API definition but with every `method`
-     * mapped to an instance of the `Operation` class.
+     * mapped to an instance of the `Webhook` class.
      *
      * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#oasObject}
      * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#openapi-object}

package/dist/operation.d.ts

@@ -59,8 +59,8 @@ export default class Operation {
      */
     getSecurity(): RMOAS.SecurityRequirementObject[];
     /**
-     * Retrieve a collection of grouped security schemes. The inner array determines and-grouped
-     * security schemes, the outer array determines or-groups.
+     * Retrieve a collection of grouped security schemes. The inner array determines AND-grouped
+     * security schemes, the outer array determines OR-groups.
      *
      * @see {@link https://swagger.io/docs/specification/authentication/#multiple}
      * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#security-requirement-object}

package/dist/operation.js

@@ -108,7 +108,7 @@ var Operation = /** @class */ (function () {
         }
         // Favor JSON if it exists
         types.forEach(function (t) {
-            if (t.match(/json/)) {
+            if (matches_mimetype_1["default"].json(t)) {
                 _this.contentType = t;
             }
         });
@@ -140,8 +140,8 @@ var Operation = /** @class */ (function () {
         return this.schema.security || this.api.security || [];
     };
     /**
-     * Retrieve a collection of grouped security schemes. The inner array determines and-grouped
-     * security schemes, the outer array determines or-groups.
+     * Retrieve a collection of grouped security schemes. The inner array determines AND-grouped
+     * security schemes, the outer array determines OR-groups.
      *
      * @see {@link https://swagger.io/docs/specification/authentication/#multiple}
      * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#security-requirement-object}
@@ -309,8 +309,8 @@ var Operation = /** @class */ (function () {
         function sanitize(id) {
             return id
                 .replace(/[^a-zA-Z0-9_]/g, '-') // Remove weird characters
-                .replace(/^-|-$/g, '') // Don't start or end with -
-                .replace(/--+/g, '-'); // Remove double --'s
+                .replace(/--+/g, '-') // Remove double --'s
+                .replace(/^-|-$/g, ''); // Don't start or end with -
         }
         var operationId;
         if (this.hasOperationId()) {

package/package.json

@@ -1,22 +1,18 @@
 {
   "name": "oas",
-  "version": "19.0.3",
-  "description": "Working with OpenAPI definitions is hard. This makes it easier.",
+  "version": "20.0.0",
+  "description": "Comprehensive tooling for working with OpenAPI definitions",
   "license": "MIT",
   "author": "ReadMe <support@readme.io> (https://readme.com)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "bin": {
-    "oas": "bin/oas"
-  },
   "engines": {
-    "node": ">=12"
+    "node": ">=14"
   },
   "tags": [
     "api",
     "apis",
     "openapi",
-    "swagger",
     "openapi initiative",
     "openapi specification",
     "openapi spec",
@@ -37,11 +33,13 @@
   "scripts": {
     "build": "tsc",
     "lint": "eslint . --ext .js,.ts",
+    "lint:docs": "npx alex .",
     "prebuild": "rm -rf dist/",
     "prepack": "npm run build",
     "prepare": "husky install",
     "pretest": "npm run lint",
-    "prettier": "prettier --list-different --write \"./**/**.{js,ts}\"",
+    "prettier": "prettier --list-different \"./**/**.{js,ts,md}\"",
+    "prettier:write": "prettier --list-different --write \"./**/**.{js,ts,md}\"",
     "release": "npx conventional-changelog-cli -i CHANGELOG.md -s && git add CHANGELOG.md",
     "test": "tsc; jest --coverage",
     "test-watch": "tsc; jest --watch",
@@ -50,33 +48,26 @@
   "dependencies": {
     "@readme/json-schema-ref-parser": "^1.1.0",
     "@types/json-schema": "^7.0.11",
-    "cardinal": "^2.1.1",
-    "chalk": "^4.1.2",
-    "glob": "^8.0.1",
-    "inquirer": "^8.1.2",
     "json-schema-merge-allof": "^0.8.1",
-    "json2yaml": "^1.1.0",
     "jsonpath": "^1.1.1",
     "jsonpointer": "^5.0.0",
     "memoizee": "^0.4.14",
-    "minimist": "^1.2.0",
-    "oas-normalize": "^7.0.0",
+    "oas-normalize": "^7.1.0",
     "openapi-types": "^12.0.0",
-    "path-to-regexp": "^6.2.0",
-    "swagger-inline": "^6.0.0"
+    "path-to-regexp": "^6.2.0"
   },
   "devDependencies": {
     "@commitlint/cli": "^17.0.2",
     "@commitlint/config-conventional": "^17.0.2",
-    "@readme/eslint-config": "^10.0.0",
-    "@readme/oas-examples": "^5.4.1",
+    "@readme/eslint-config": "^10.1.1",
+    "@readme/oas-examples": "^5.7.1",
     "@readme/openapi-parser": "^2.2.0",
     "@types/jest": "^28.1.6",
     "@types/json-schema-merge-allof": "^0.6.1",
     "@types/jsonpath": "^0.2.0",
     "@types/memoizee": "^0.4.6",
-    "@types/node": "^18.8.2",
-    "eslint": "^8.20.0",
+    "@types/node": "^18.11.7",
+    "eslint": "^8.26.0",
     "husky": "^8.0.1",
     "jest": "^28.1.3",
     "prettier": "^2.6.2",

package/src/index.ts

@@ -695,7 +695,7 @@ export default class Oas {
 
   /**
    * Returns the `webhooks` object that exists in this API definition but with every `method`
-   * mapped to an instance of the `Operation` class.
+   * mapped to an instance of the `Webhook` class.
    *
    * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#oasObject}
    * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#openapi-object}

package/src/operation.ts

@@ -116,7 +116,7 @@ export default class Operation {
 
     // Favor JSON if it exists
     types.forEach(t => {
-      if (t.match(/json/)) {
+      if (matchesMimeType.json(t)) {
         this.contentType = t;
       }
     });
@@ -155,8 +155,8 @@ export default class Operation {
   }
 
   /**
-   * Retrieve a collection of grouped security schemes. The inner array determines and-grouped
-   * security schemes, the outer array determines or-groups.
+   * Retrieve a collection of grouped security schemes. The inner array determines AND-grouped
+   * security schemes, the outer array determines OR-groups.
    *
    * @see {@link https://swagger.io/docs/specification/authentication/#multiple}
    * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#security-requirement-object}
@@ -342,8 +342,8 @@ export default class Operation {
     function sanitize(id: string) {
       return id
         .replace(/[^a-zA-Z0-9_]/g, '-') // Remove weird characters
-        .replace(/^-|-$/g, '') // Don't start or end with -
-        .replace(/--+/g, '-'); // Remove double --'s
+        .replace(/--+/g, '-') // Remove double --'s
+        .replace(/^-|-$/g, ''); // Don't start or end with -
     }
 
     let operationId;

package/tsconfig.json

@@ -9,6 +9,5 @@
     "outDir": "./dist",
     "resolveJsonModule": true,
   },
-  "include": ["./src/**/*"],
-  "exclude": ["./src/cli/*"]
+  "include": ["./src/**/*"]
 }

package/bin/oas

@@ -1,8 +0,0 @@
-#! /usr/bin/env node
-const parseArgs = require('minimist')(process.argv.slice(2));
-
-const args = parseArgs._;
-const opts = Object.assign(parseArgs, {});
-delete opts._;
-
-require('../src/cli')(args, opts);

package/src/cli/commands/endpoint.js

@@ -1,31 +0,0 @@
-const chalk = require('chalk');
-
-const utils = require('../lib/utils');
-
-exports.swagger = false;
-exports.desc = 'Learn how to document an endpoint';
-exports.weight = 3;
-
-exports.run = function () {
-  console.log('You can document each API endpoint right alongside your code!');
-  console.log('');
-  console.log('Use the following syntax in a comment block above the the code:');
-  console.log('');
-
-  console.log(utils.swaggerInlineExample(utils.guessLanguage()));
-
-  console.log('');
-  console.log(`${chalk.blue('Parameter shorthand:')} Since parameters can be very verbose, we have a shorthand`);
-  console.log('syntax for describing them.');
-
-  console.log('');
-  console.log(chalk.grey('  - (in) name=default* {type:format} description'));
-  console.log('');
-
-  console.log('This will be expanded when the OpenAPI definition is compiled.');
-
-  console.log('');
-  console.log(`For more information on this syntax, see ${chalk.yellow('https://github.com/readmeio/swagger-inline')}`);
-
-  process.exit();
-};

package/src/cli/commands/generate.js

@@ -1,14 +0,0 @@
-const cardinal = require('cardinal');
-
-exports.swagger = true;
-exports.desc = 'Output your OpenAPI definition (use --pretty for colors)';
-
-exports.run = function (info) {
-  if (info.opts.pretty || info.opts.p) {
-    console.log(cardinal.highlight(JSON.stringify(info.swagger, undefined, 2)));
-  } else {
-    console.log(JSON.stringify(info.swagger, undefined, 2));
-  }
-
-  process.exit();
-};

package/src/cli/commands/help.js

@@ -1,59 +0,0 @@
-const path = require('path');
-
-const chalk = require('chalk');
-const glob = require('glob');
-
-exports.swagger = false;
-exports.desc = 'Learn what you can do with oas';
-exports.weight = 2;
-
-function pad(text) {
-  return `${text}                          `.substr(0, 23);
-}
-
-exports.run = function () {
-  console.log('');
-  console.log('Usage: oas <command>');
-  console.log('');
-
-  const files = glob.sync(path.join(__dirname, '*'));
-  const commands = [];
-
-  files.forEach(function (file) {
-    const action = file.match(/(\w+).js/)[1];
-
-    // eslint-disable-next-line import/no-dynamic-require, global-require
-    const cmd = require(file);
-    const desc = cmd.desc || '';
-
-    let cmdUsage;
-    if (cmd.swagger) {
-      cmdUsage = `${pad(`${action} [oas.json]`)} ${chalk.grey(desc)}`;
-      cmdUsage = cmdUsage.replace(/\[oas\.json\]/, chalk.grey('[oas.json]'));
-    } else {
-      cmdUsage = `${pad(action)} ${chalk.grey(desc)}`;
-    }
-
-    commands.push({
-      msg: `  ${chalk.grey('$')} oas ${cmdUsage}`,
-      weight: cmd.weight || 100,
-    });
-  });
-
-  commands.sort((a, b) => {
-    if (a.weight > b.weight) return 1;
-    return b.weight > a.weight ? -1 : 0;
-  });
-
-  commands.forEach(function (command) {
-    console.log(command.msg);
-  });
-
-  console.log('');
-  console.log(
-    `${chalk.green('Just getting started?')} Run ${chalk.yellow('oas init')} to create your OpenAPI definition.`
-  );
-  console.log('');
-
-  process.exit();
-};

package/src/cli/commands/init.js

@@ -1,135 +0,0 @@
-const fs = require('fs');
-const path = require('path');
-
-const chalk = require('chalk');
-const inquirer = require('inquirer');
-const YAML = require('json2yaml');
-
-const utils = require('../lib/utils');
-
-exports.swagger = false;
-exports.desc = 'Create a new OpenAPI definition';
-exports.weight = 1;
-
-function writeFile(output, swagger) {
-  let body = JSON.stringify(swagger, undefined, 2);
-  if (output.match(/.(yaml|yml)/)) {
-    body = YAML.stringify(swagger);
-    body = body.replace(/^\s\s/gm, '').replace(/^---\n/, '');
-  }
-  fs.writeFileSync(output, body);
-}
-
-exports.run = function () {
-  console.log(`This will help you set up an ${chalk.cyan('OpenAPI 3.0 Definition')} in your codebase, so`);
-  console.log('you can start documenting your API!');
-  console.log('');
-
-  let pkg = {};
-  if (fs.existsSync('./package.json')) {
-    // eslint-disable-next-line import/no-dynamic-require, global-require
-    pkg = require(path.join(process.cwd(), '/package.json'));
-  }
-
-  const questions = [
-    {
-      type: 'input',
-      name: 'info.title',
-      message: 'Name of the API',
-      default: pkg.name || process.cwd().split('/').slice(-1)[0],
-    },
-    {
-      type: 'input',
-      name: 'info.version',
-      message: 'Version number',
-      default: pkg.version || '1.0.0',
-    },
-    {
-      type: 'input',
-      name: 'info.license',
-      message: 'License',
-      default: pkg.license,
-    },
-    {
-      type: 'input',
-      name: 'url',
-      message: 'Full Base URL',
-      validate(value) {
-        const pass = /^(http|https|ws|wss):\/\/[^ "]+$/.test(value);
-        if (pass) {
-          return true;
-        }
-
-        return 'Please enter a valid URL, including the protocol.';
-      },
-    },
-    {
-      type: 'input',
-      name: 'output',
-      message: 'Output JSON or YAML file',
-      validate(value) {
-        const pass = /.(json|yaml|yml)$/.test(value);
-        const doesntExist = !utils.fileExists(value);
-
-        if (pass && doesntExist) {
-          return true;
-        }
-
-        if (!pass) {
-          return 'Your file must end with .json or .yaml';
-        }
-
-        return 'This file already exists';
-      },
-    },
-  ];
-
-  inquirer.prompt(questions).then(function (answers) {
-    const swagger = {
-      openapi: '3.0.0',
-      info: {
-        version: answers.info.version,
-        title: answers.info.title,
-      },
-      servers: [
-        {
-          url: answers.url,
-        },
-      ],
-      paths: {},
-    };
-
-    if (answers.info.license) {
-      swagger.info.license = {
-        name: answers.info.license,
-      };
-    }
-
-    writeFile(answers.output, swagger);
-
-    console.log('');
-    console.log('======================');
-    console.log('');
-    console.log(chalk.green('SUCCESS!'));
-    console.log('');
-    console.log(`We've created your new OpenAPI file at ${chalk.yellow(answers.output)}.`);
-    console.log('');
-    console.log('You can document each endpoint right above the code. Just use the');
-    console.log('following syntax in a comment above the code:');
-    console.log('');
-
-    console.log(utils.swaggerInlineExample(utils.guessLanguage()));
-
-    console.log('');
-    console.log('For more information on this syntax, see https://github.com/readmeio/swagger-inline');
-    console.log('');
-    console.log(`To see what you can do with your API, type ${chalk.yellow('oas help')}.`);
-    console.log('');
-    console.log(
-      `To generate an OAS file, type ${chalk.yellow('oas generate')}. To publish it, type ${chalk.yellow('oas host')}!`
-    );
-    console.log('');
-
-    process.exit();
-  });
-};

package/src/cli/commands/validate.js

@@ -1,9 +0,0 @@
-const chalk = require('chalk');
-
-exports.swagger = true;
-exports.desc = 'Validate your OpenAPI definition';
-
-exports.run = function () {
-  console.log(`${chalk.green('✔ Success!')} Your OpenAPI definition is valid!`);
-  process.exit();
-};

package/src/cli/index.js

@@ -1,46 +0,0 @@
-const path = require('path');
-
-const chalk = require('chalk');
-
-const utils = require('./lib/utils');
-
-function loadAction(action = 'help') {
-  const file = path.join(__dirname, 'commands', `${action}.js`);
-  if (utils.fileExists(file)) {
-    // eslint-disable-next-line import/no-dynamic-require, global-require
-    return require(file);
-  }
-
-  console.log(chalk.red('Action not found.'));
-  console.log(`Type ${chalk.yellow('oas help')} to see all commands`);
-  return process.exit(1);
-}
-
-module.exports = function (args, opts) {
-  opts = opts || {};
-
-  const cmd = loadAction(args[0]);
-  if (!cmd) {
-    return;
-  }
-
-  const info = {
-    args,
-    opts,
-  };
-
-  if (cmd.swagger) {
-    utils.findSwagger(info, function (err, swagger) {
-      if (err) {
-        console.error(err);
-        return;
-      }
-
-      info.swagger = swagger;
-
-      cmd.run(info);
-    });
-  } else {
-    cmd.run(info);
-  }
-};

package/src/cli/lib/utils.js

@@ -1,184 +0,0 @@
-const fs = require('fs');
-
-const cardinal = require('cardinal');
-const chalk = require('chalk');
-const glob = require('glob');
-const OASNormalize = require('oas-normalize').default;
-const swaggerInline = require('swagger-inline');
-
-exports.findSwagger = async function (info, cb) {
-  const file = info.args[info.args.length - 1];
-  const base = exports.isJSONOrYaml(file) ? file : undefined;
-
-  if (!base) {
-    console.error(
-      `You must pass a base OpenAPI or Swagger definition into ${chalk.yellow('oas generate')} to build off of.`
-    );
-
-    console.error('');
-    console.error('This base specification might look like the following:');
-    console.error(
-      cardinal.highlight(
-        JSON.stringify(
-          {
-            openapi: '3.0.3',
-            info: {
-              title: 'Example OpenAPI base file for `oas`.',
-              version: '1.0',
-            },
-            servers: [
-              {
-                url: 'https://api.example.com',
-              },
-            ],
-          },
-          null,
-          2
-        )
-      )
-    );
-
-    console.error('');
-    console.error(
-      `And supply that to ${chalk.yellow('oas generate')} as ${chalk.yellow('oas generate openapiBase.json')}`
-    );
-    process.exit(1);
-  }
-
-  let pathGlob = info.opts.pathGlob || '**/*';
-  if (info.opts.path) {
-    pathGlob = `${info.opts.path.replace(/\/$/, '')}/*`;
-  }
-
-  const generatedDefinition = await swaggerInline(pathGlob, {
-    format: '.json',
-    scope: info.opts.scope,
-    base,
-    pattern: info.opts.pattern || null,
-  }).catch(err => {
-    console.error(err);
-    process.exit(1);
-  });
-
-  let oas = new OASNormalize(generatedDefinition);
-  const bundledDefinition = await oas.bundle().catch(err => {
-    console.error(err.message);
-    process.exit(1);
-  });
-
-  oas = new OASNormalize(bundledDefinition, { colorizeErrors: true });
-  await oas
-    .validate()
-    .then(schema => cb(undefined, schema))
-    .catch(err => {
-      if (info.opts.v) {
-        console.log(cardinal.highlight(generatedDefinition));
-      }
-
-      console.log('');
-      console.log(
-        [
-          chalk.red('Error validating the API definition!'),
-          !info.opts.v ? `Run with ${chalk.grey('-v')} to see the invalid definition.` : '',
-        ].join(' ')
-      );
-      console.log('');
-
-      console.log(err.message);
-      console.log('');
-      process.exit(1);
-    });
-};
-
-exports.isJSONOrYaml = function (file) {
-  return Boolean(['.json', '.yaml', '.yml'].map(ext => file.endsWith(ext)).filter(Boolean).length);
-};
-
-exports.fileExists = function (file) {
-  try {
-    return fs.statSync(file).isFile();
-  } catch (err) {
-    return false;
-  }
-};
-
-/**
- * Really simple way at guessing the language that their API might be written in. If we're wrong,
- * it's not a big deal!
- *
- * @returns {String}
- */
-exports.guessLanguage = function () {
-  let language = 'js';
-  let languages = {
-    rb: 0,
-    coffee: 0,
-    py: 0,
-    js: 0,
-    java: 0,
-    php: 0,
-    go: 0,
-  };
-
-  const files = glob.sync('*');
-  files.forEach(function (f) {
-    const ext = f.split('.').slice(-1)[0];
-    if (typeof languages[ext] !== 'undefined') {
-      languages[ext] += 1;
-    }
-  });
-
-  languages = Object.entries(languages).filter(lang => lang[1] > 0);
-  if (languages.length > 0) {
-    languages.sort(function (a, b) {
-      if (a[1] > b[1]) return 1;
-      return b[1] > a[1] ? -1 : 0;
-    });
-
-    languages.reverse();
-
-    language = languages.shift()[0];
-  }
-
-  return language;
-};
-
-exports.swaggerInlineExample = function (lang) {
-  const prefix = '  ';
-
-  const annotation = [
-    '@oas [get] /pet/{petId}',
-    'description: Returns all pets from the system that the user has access to',
-    'parameters:',
-    '  - (path) petId=2* {Integer} The pet ID',
-    '  - (query) limit {Integer:int32} The number of resources to return',
-  ];
-
-  const languages = {
-    js: ['/*', ' * ', ' */', 'route.get("/pet/:petId", pet.show);'],
-    jsx: ['/*', ' * ', ' */', 'route.get("/pet/:petId", pet.show);'],
-    ts: ['/*', ' * ', ' */', 'route.get("/pet/:petId", pet.show);'],
-    java: ['/*', ' * ', ' */', 'public String getPet(id) {'],
-    php: ['/*', ' * ', ' */', 'function showPet($id) {'],
-    coffee: ['###', '', '###', "route.get '/pet/:petId', pet.show"],
-    rb: ['=begin', '', '=end', "get '/pet/:petId' do"],
-    py: ['"""', '', '"""', 'def getPet(id):'],
-    go: ['/*', ' * ', ' */', 'func getPet(id) {'],
-  };
-
-  lang = lang.toLowerCase();
-  if (!lang || !languages[lang]) lang = 'javascript';
-
-  const language = languages[lang];
-
-  const out = [`${prefix}${chalk.cyan(language[0])}`];
-
-  annotation.forEach(function (line) {
-    out.push(`${prefix}${chalk.cyan(language[1])}${chalk.cyan(line)}`);
-  });
-
-  out.push(`${prefix}${chalk.cyan(language[2])}`);
-  out.push(`${prefix}${chalk.grey(language[3])}`);
-
-  return out.join('\n');
-};