Rename SwaggerApi to ApiDefinition

Part of #128
apigee-127 · Dec 3, 2018 · 4719e72 · 4719e72
1 parent f38ff54
commit 4719e72
Show file tree

Hide file tree

Showing 26 changed files with 1,640 additions and 1,626 deletions.
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -3,6 +3,9 @@
 ### v3.0.0 (TBD)
 
 * OpenAPI _v3.x_ support *(Issue #128)*
+* API Changes
+    * `Path.api` -> `Path.apiDefinition`
+    * `SwaggerApi` -> `ApiDefinition`
 
 ### v2.0.4 (2018-08-31)
 

diff --git a/browser/sway-min.js b/browser/sway-min.js
diff --git a/browser/sway-standalone-min.js b/browser/sway-standalone-min.js
diff --git a/browser/sway-standalone.js b/browser/sway-standalone.js
diff --git a/browser/sway.js b/browser/sway.js
diff --git a/docs/API.md b/docs/API.md
diff --git a/index.d.ts b/index.d.ts
@@ -1,20 +1,20 @@
 /**
- * A library for simpler [Swagger](http://swagger.io/) integrations.
+ * A library that simplifies [OpenAPI](https://www.openapis.org/) integrations.
  */
 declare module 'sway' {
     /**
-     * Creates a SwaggerApi object from its Swagger definition(s).
+     * Creates an ApiDefinition object from the provided OpenAPI definition.
      * @param options - The options for loading the definition(s)
      * @returns The promise
      */
-    export function create(options: CreateOptions): Promise<SwaggerApi>;
+    export function create(options: CreateOptions): Promise<ApiDefinition>;
 
     /**
-     * Options used when creating the `SwaggerApi`.
+     * Options used when creating the `ApiDefinition`.
      */
     interface CreateOptions {
         /**
-         * The Swagger definition location or structure
+         * The OpenAPI definition location or structure
          */
         definition: object | string;
         /**
@@ -38,11 +38,11 @@ declare module 'sway' {
     }
 
     /**
-     * Function used for custom validation of Swagger documents
-     * @param api - The Swagger API object
+     * Function used for custom validation of OpenAPI documents
+     * @param apiDefinition - The `ApiDefinition` object
      * @returns The validation results
      */
-    export type DocumentValidationFunction = (api: SwaggerApi)=>ValidationResults;
+    export type DocumentValidationFunction = (apiDefinition: ApiDefinition)=>ValidationResults;
 
     /**
      * Request validation function.
@@ -60,9 +60,9 @@ declare module 'sway' {
     interface RequestValidationOptions {
         /**
          * Enablement of strict mode validation.  If `strictMode` is a
-         * `boolean` and is `true`, all form fields, headers and query parameters **must** be defined in the Swagger document
+         * `boolean` and is `true`, all form fields, headers and query parameters **must** be defined in the OpenAPI document
          * for this operation.  If `strictMode` is an `object`, the keys correspond to the `in` property values of the
-         * [Swagger Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#parameterObject)
+         * [OpenAPI Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#parameterObject)
          * and its value is a `boolean` that when `true` turns on strict mode validation for the request location matching the
          * key.  Valid keys are `formData`, `header` and `query`.  _(`body` and `path` are not necessary since `body` strict
          * mode is possible via its schema and `path` is **always** required.)_
@@ -88,9 +88,9 @@ declare module 'sway' {
     interface ResponseValidationOptions {
         /**
          * Enablement of strict mode validation.  If `strictMode` is a
-         * `boolean` and is `true`, all form fields, headers and query parameters **must** be defined in the Swagger document
+         * `boolean` and is `true`, all form fields, headers and query parameters **must** be defined in the OpenAPI definition
          * for this operation.  If `strictMode` is an `object`, the keys correspond to the `in` property values of the
-         * [Swagger Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#parameterObject)
+         * [OpenAPI Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#parameterObject)
          * and its value is a `boolean` that when `true` turns on strict mode validation for the request location matching the
          * key.  Valid keys are `header`.  _(`body`, `query` and `path` are not necessary since `body` strict mode is possible
          * via its schema and `path`, `query` do not matter for responses.)_
@@ -190,19 +190,19 @@ declare module 'sway' {
         warnings: any[];
     }
 
-    class SwaggerApi {
+    class ApiDefinition {
         /**
-         * The Swagger API object.
+         * The OpenAPI Definition object.
          * 
          * **Note:** Do not use directly.
          * 
-         * **Extra Properties:** Other than the documented properties, this object also exposes all properties of the definition
-         * object.
-         * @param definition - The original Swagger definition
-         * @param definitionRemotesResolved - The Swagger definition with all of its remote references resolved
-         * @param definitionFullyResolved - The Swagger definition with all of its references resolved
-         * @param references - The location and resolution of the resolved references in the Swagger definition
-         * @param options - The options passed to swaggerApi.create
+         * **Extra Properties:** Other than the documented properties, this object also exposes all properties of the
+         * [OpenAPI Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#openapi-object).
+         * @param definition - The original OpenAPI definition
+         * @param definitionRemotesResolved - The OpenAPI definition with all of its remote references resolved
+         * @param definitionFullyResolved - The OpenAPI definition with all of its references resolved
+         * @param references - The location and resolution of the resolved references in the OpenAPI definition
+         * @param options - The options passed to ApiDefinition.create
          */
         constructor(definition: object, definitionRemotesResolved: object, definitionFullyResolved: object, references: object, options: object);
 
@@ -216,24 +216,24 @@ declare module 'sway' {
          * * `url`
          * 
          * *(See: {@link https://nodejs.org/api/http.html#http_class_http_clientrequest})*
-         * @param idOrPathOrReq - The Swagger opeartion id, path string or the http client request *(or
+         * @param idOrPathOrReq - The OpenAPI opeartion id, path string or the http client request *(or
          *        equivalent)*
-         * @param method - The Swagger operation method _(not used when providing an operation id)_
+         * @param method - The OpenAPI operation method _(not used when providing an operation id)_
          * @returns The `Operation` for the provided operation id, or path and method or `undefined` if
          *          there is no operation for that operation id, or path and method combination
          */
         getOperation(idOrPathOrReq: string | object, method?: string): Operation;
 
         /**
          * Returns all operations for the provided path or all operations in the API.
-         * @param path - The Swagger path
+         * @param path - The OpenAPI path
          * @returns All `Operation` objects for the provided path or all API operations
          */
         getOperations(path?: string): any[];
 
         /**
          * Returns all operations for the provided tag.
-         * @param tag - The Swagger tag
+         * @param tag - The OpenAPI tag
          * @returns All `Operation` objects for the provided tag
          */
         getOperationsByTag(tag?: string): any[];
@@ -247,13 +247,13 @@ declare module 'sway' {
          * * `url`
          * 
          * *(See: {@link https://nodejs.org/api/http.html#http_class_http_clientrequest})*
-         * @param pathOrReq - The Swagger path string or the http client request *(or equivalent)*
+         * @param pathOrReq - The OpenAPI path string or the http client request *(or equivalent)*
          * @returns The corresponding `Path` object for the requested path or request
          */
         getPath(pathOrReq: string | object): Path;
 
         /**
-         * Returns all path objects for the Swagger API.
+         * Returns all path objects for the OpenAPI definition.
          * @returns The `Path` objects
          */
         getPaths(): any[];
@@ -292,7 +292,7 @@ declare module 'sway' {
         registerValidator(validator: DocumentValidationFunction): void;
 
         /**
-         * Performs validation of the Swagger API document(s).
+         * Performs validation of the OpenAPI definition.
          * @returns The validation results
          */
         validate(): ValidationResults;
@@ -301,12 +301,12 @@ declare module 'sway' {
 
     class Operation {
         /**
-         * The Swagger Operation object.
+         * The OpenAPI Operation object.
          * 
          * **Note:** Do not use directly.
          * 
-         * **Extra Properties:** Other than the documented properties, this object also exposes all properties of the definition
-         * object.
+         * **Extra Properties:** Other than the documented properties, this object also exposes all properties of the
+         * [OpenAPI Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#operationObject).
          * @param pathObject - The Path object
          * @param method - The operation method
          * @param definition - The operation definition *(The raw operation definition __after__ remote references were
@@ -400,12 +400,12 @@ declare module 'sway' {
 
     class Parameter {
         /**
-         * The Swagger Parameter object.
+         * The OpenAPI Parameter object.
          * 
          * **Note:** Do not use directly.
          * 
-         * **Extra Properties:** Other than the documented properties, this object also exposes all properties of the definition
-         * object.
+         * **Extra Properties:** Other than the documented properties, this object also exposes all properties of the
+         * [OpenAPI Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#parameterObject).
          * @param opOrPathObject - The `Operation` or `Path` object
          * @param definition - The parameter definition *(The raw parameter definition __after__ remote references were
          *        resolved)*
@@ -452,15 +452,15 @@ declare module 'sway' {
          * **Note:** Do not use directly.
          * 
          * **Extra Properties:** Other than the documented properties, this object also exposes all properties of the
-         * definition object.
-         * @param api - The `SwaggerApi` object
+         * [OpenAPI Path Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#pathItemObject).
+         * @param apiDefinition - The `ApiDefinition` object
          * @param path - The path string
          * @param definition - The path definition *(The raw path definition __after__ remote references were
          *        resolved)*
          * @param definitionFullyResolved - The path definition with all of its resolvable references resolved
          * @param pathToDefinition - The path segments to the path definition
          */
-        constructor(api: SwaggerApi, path: string, definition: object, definitionFullyResolved: object, pathToDefinition: string[]);
+        constructor(apiDefinition: ApiDefinition, path: string, definition: object, definitionFullyResolved: object, pathToDefinition: string[]);
 
         /**
          * Return the operation for this path and operation id or method.
@@ -493,12 +493,12 @@ declare module 'sway' {
 
     class Response {
         /**
-         * The Swagger Response object.
+         * The OpenAPI Response object.
          * 
          * **Note:** Do not use directly.
          * 
          * **Extra Properties:** Other than the documented properties, this object also exposes all properties of the
-         * definition object.
+         * [OpenAPI Response Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#responseObject).
          * @param operationObject - The `Operation` object
          * @param statusCode - The status code
          * @param definition - The response definition *(The raw response definition __after__ remote references were

diff --git a/index.js b/index.js
@@ -27,7 +27,7 @@
 var _ = require('lodash');
 var helpers = require('./lib/helpers');
 var JsonRefs = require('json-refs');
-var SwaggerApi = require('./lib/types/api');
+var ApiDefinition = require('./lib/types/api-definition');
 var YAML = require('js-yaml');
 
 // Load promises polyfill if necessary
@@ -37,25 +37,27 @@ if (typeof Promise === 'undefined') {
 }
 
 /**
- * A library for simpler [Swagger](http://swagger.io/) integrations.
+ * A library that simplifies [OpenAPI](https://www.openapis.org/) integrations.
  *
  * @module sway
  */
 
 /**
- * Creates a SwaggerApi object from its Swagger definition(s).
+ * Creates an ApiDefinition object from the provided OpenAPI definition.
  *
  * @param {module:sway.CreateOptions} options - The options for loading the definition(s)
  *
- * @returns {Promise<module:sway.SwaggerApi>} The promise
+ * @returns {Promise<module:sway.ApiDefinition>} The promise
  *
  * @example
- * SwaggerApi.create({definition: 'http://petstore.swagger.io/v2/swagger.yaml'})
- *   .then(function (api) {
- *     console.log('Documentation URL: ', api.documentationUrl);
- *   }, function (err) {
- *     console.error(err.stack);
- *   });
+ * Sway.create({
+ *   definition: 'https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v3.0/petstore.yaml'
+ * })
+ * .then(function (apiDefinition) {
+ *   console.log('Documentation URL: ', api.documentationUrl);
+ * }, function (err) {
+ *   console.error(err.stack);
+ * });
  */
 module.exports.create = function (options) {
   var allTasks = Promise.resolve();
@@ -138,18 +140,18 @@ module.exports.create = function (options) {
           });
 
           return {
-            // The original Swagger definition
+            // The original OpenAPI definition
             definition: _.isString(cOptions.definition) ? remoteResults.value : cOptions.definition,
-            // The original Swagger definition with its remote references resolved
+            // The original OpenAPI definition with its remote references resolved
             definitionRemotesResolved: remoteResults.resolved,
-            // The original Swagger definition with all its references resolved
+            // The original OpenAPI definition with all its references resolved
             definitionFullyResolved: results.resolved,
             // Merge the local reference details with the remote reference details
             refs: results.refs
           }
         });
     })
-    // Process the Swagger document and return the API
+    // Process the OpenAPI document and return an ApiDefinition
     .then(function (results) {
       // We need to remove all circular objects as z-schema does not work with them:
       //   https://github.com/zaggino/z-schema/issues/137
@@ -158,7 +160,7 @@ module.exports.create = function (options) {
       helpers.removeCirculars(results.definitionFullyResolved);
 
       // Create object model
-      return new SwaggerApi(results.definition,
+      return new ApiDefinition(results.definition,
                             results.definitionRemotesResolved,
                             results.definitionFullyResolved,
                             results.refs,

diff --git a/lib/helpers.js b/lib/helpers.js
@@ -60,7 +60,7 @@ var dateTimeRegExp = new RegExp(
 var collectionFormats = [undefined, 'csv', 'multi', 'pipes', 'ssv', 'tsv'];
 var jsonMocker;
 var jsonSchemaValidator = createJSONValidator();
-// https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#parameter-object
+// https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#parameterObject
 var parameterSchemaProperties = [
   'allowEmptyValue',
   'default',
@@ -181,9 +181,9 @@ function normalizeError (obj) {
 }
 
 /**
- * Helper method to take a Swagger parameter definition and compute its schema.
+ * Helper method to take an OpenAPI Parameter Object definition and compute its schema.
  *
- * For non-body Swagger parameters, the definition itself is not suitable as a JSON Schema so we must compute it.
+ * For non-body OpenAPI parameters, the definition itself is not suitable as a JSON Schema so we must compute it.
  *
  * @param {object} paramDef - The parameter definition
  *
@@ -462,7 +462,7 @@ module.exports.parameterLocations = ['body', 'formData', 'header', 'path', 'quer
  * Process validators.
  *
  * @param {object|module:Sway~ServerResponseWrapper} target - The thing being validated
- * @param {module:Sway~SwaggerApi|module:Sway~Operation|module:Sway~Response} caller - The object requesting validation _(can be `undefined`)_
+ * @param {module:Sway~ApiDefinition|module:Sway~Operation|module:Sway~Response} caller - The object requesting validation _(can be `undefined`)_
  * @param {module:Sway~DocumentValidationFunction[]|module:Sway~RequestValidationFunction[]|module:Sway~ResposeValidationFunction[]} validators - The validators
  * @param {module:Sway~ValidationResults} results - The cumulative validation results
  */