oas 17.2.0 → 17.3.0

package/@types/lib/openapi-to-json-schema.d.ts

@@ -1,4 +1,18 @@
-export = toJSONSchema;
+import * as RMOAS from '../rmoas.types';
+declare type PrevSchemasType = Array<RMOAS.SchemaObject>;
+export declare type toJsonSchemaOptions = {
+    currentLocation?: string;
+    globalDefaults?: {
+        [key: string]: unknown;
+    };
+    isPolymorphicAllOfChild?: boolean;
+    prevSchemas?: PrevSchemasType;
+    refLogger?: (ref: string) => void;
+};
+/**
+ * @param val
+ */
+export declare function isPrimitive(val: unknown): boolean;
 /**
  * Given an OpenAPI-flavored JSON Schema, make an effort to modify it so it's shaped more towards stock JSON Schema.
  *
@@ -26,26 +40,15 @@ export = toJSONSchema;
  * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md}
  * @param {Object} data
  * @param {Object} opts
- * @param {String} opts.currentLocation - Current location within the schema -- this is a JSON pointer.
+ * @param {string} opts.currentLocation - Current location within the schema -- this is a JSON pointer.
  * @param {Object} opts.globalDefaults - Object containing a global set of defaults that we should apply to schemas that match it.
- * @param {Boolean} opts.isPolymorphicAllOfChild - Is this schema the child of a polymorphic `allOf` schema?
+ * @param {boolean} opts.isPolymorphicAllOfChild - Is this schema the child of a polymorphic `allOf` schema?
  * @param {Object[]} opts.prevSchemas - Array of parent schemas to utilize when attempting to path together examples.
  * @param {Function} opts.refLogger - A function that's called anytime a (circular) `$ref` is found.
  */
-declare function toJSONSchema(data: Object, opts?: {
-    currentLocation: string;
-    globalDefaults: Object;
-    isPolymorphicAllOfChild: boolean;
-    prevSchemas: Object[];
-    refLogger: Function;
-}): {
-    constructor: Function;
-    toString(): string;
-    toLocaleString(): string;
-    valueOf(): Object;
-    hasOwnProperty(v: PropertyKey): boolean;
-    isPrototypeOf(v: Object): boolean;
-    propertyIsEnumerable(v: PropertyKey): boolean;
-} | {
-    $ref: any;
-};
+/**
+ * @param data
+ * @param opts
+ */
+export default function toJSONSchema(data: RMOAS.SchemaObject | RMOAS.RequestBodyObject, opts?: toJsonSchemaOptions): RMOAS.SchemaObject;
+export {};

package/@types/operation/get-callback-examples.d.ts

@@ -1,10 +1,10 @@
 import type * as RMOAS from '../rmoas.types';
-export declare type CallbackExamples = {
+export declare type CallbackExamples = Array<{
     identifier: string;
     expression: string;
     method: string;
     example: unknown;
-}[];
+}>;
 /**
  * With an OpenAPI Operation Object return back an array of examples for any callbacks that may be present.
  *

package/@types/operation/get-parameters-as-json-schema.d.ts

@@ -1,13 +1,21 @@
-declare function _exports(path: string, operation: Operation, api: OpenAPI.Document, globalDefaults?: Object): array<object>;
-declare namespace _exports {
-    export { types };
-}
-export = _exports;
-declare namespace types {
-    const path: string;
-    const query: string;
-    const body: string;
-    const cookie: string;
-    const formData: string;
-    const header: string;
-}
+import type { OASDocument, OperationObject, SchemaObject } from '../rmoas.types';
+import * as RMOAS from '../rmoas.types';
+export declare type SchemaWrapper = {
+    $schema?: string;
+    type: string;
+    label?: string;
+    schema: SchemaObject;
+    deprecatedProps?: SchemaWrapper;
+};
+export declare const types: {
+    [key: keyof RMOAS.OASDocument]: string;
+};
+declare const _default: (path: string, operation: OperationObject, api: OASDocument, globalDefaults?: {}) => SchemaWrapper[];
+/**
+ * @param {string} path
+ * @param {Operation} operation
+ * @param {OpenAPI.Document} api
+ * @param {Object} globalDefaults
+ * @returns {Array<object>}
+ */
+export default _default;

package/@types/operation/get-requestbody-examples.d.ts

@@ -1,8 +1,8 @@
 import type * as RMOAS from '../rmoas.types';
-export declare type RequestBodyExamples = {
+export declare type RequestBodyExamples = Array<{
     mediaType: string;
     examples: any;
-}[];
+}>;
 /**
  * @param operation Operation to retrieve requestBody examples for.
  * @returns An object of response examples keyed by their media type.

package/@types/operation/get-response-as-json-schema.d.ts

@@ -1,6 +1,18 @@
-declare function _exports(operation: any, api: any, statusCode: any): {
-    type: any;
-    schema: any;
+import type { OASDocument, SchemaObject } from 'rmoas.types';
+import type Operation from 'operation';
+/**
+ * Extract all the response schemas, matching the format of get-parameters-as-json-schema.
+ *
+ * Note: This expects a dereferenced schema.
+ *
+ * @param operation Operation to construct a response JSON Schema for.
+ * @param api The OpenAPI definition that this operation originates.
+ * @param statusCode The response status code to generate a schema for.
+ * @returns Array<{schema: Object, type: string, label: string}>
+ */
+export default function getResponseAsJsonSchema(operation: Operation, api: OASDocument, statusCode: string | number): {
+    type: string | Array<string>;
+    schema: SchemaObject;
     label: string;
+    description?: string;
 }[];
-export = _exports;

package/@types/operation/get-response-examples.d.ts

@@ -1,8 +1,8 @@
 import type * as RMOAS from '../rmoas.types';
-export declare type ResponseExamples = {
+export declare type ResponseExamples = Array<{
     status: string;
     mediaTypes: Record<string, RMOAS.MediaTypeObject>;
-}[];
+}>;
 /**
  * @param operation Operation to retrieve response examples for.
  * @returns An object of response examples keyed by their media type.

package/@types/operation.d.ts

@@ -1,13 +1,11 @@
-import type * as RMOAS from './rmoas.types';
-import type { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
 import type { RequestBodyExamples } from './operation/get-requestbody-examples';
 import type { CallbackExamples } from './operation/get-callback-examples';
 import type { ResponseExamples } from './operation/get-response-examples';
-import Oas from '.';
+import * as RMOAS from './rmoas.types';
 declare type SecurityType = 'Basic' | 'Bearer' | 'Query' | 'Header' | 'Cookie' | 'OAuth2' | 'http' | 'apiKey';
 export default class Operation {
     /**
-     * Schema of the operation from the API Definiton.
+     * Schema of the operation from the API Definition.
      */
     schema: RMOAS.OperationObject;
     /**
@@ -45,7 +43,7 @@ export default class Operation {
         request: Array<string>;
         response: Array<string>;
     };
-    constructor(api: Oas | RMOAS.OASDocument, path: string, method: RMOAS.HttpMethods, operation: RMOAS.OperationObject);
+    constructor(api: RMOAS.OASDocument, path: string, method: RMOAS.HttpMethods, operation: RMOAS.OperationObject);
     getContentType(): string;
     isFormUrlEncoded(): boolean;
     isMultipart(): boolean;
@@ -55,105 +53,114 @@ export default class Operation {
      * Returns an array of all security requirements associated wtih this operation. If none are defined at the operation
      * level, the securities for the entire API definition are returned (with an empty array as a final fallback).
      *
-     * @returns Array of security requirement objects.
+     * @returns {Array}
      */
-    getSecurity(): OpenAPIV3.SecurityRequirementObject[];
+    getSecurity(): Array<RMOAS.SecurityRequirementObject>;
     /**
      * @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}
-     * @param filterInvalid Optional flag that, when set to `true`, filters out invalid/nonexistent security schemes,
-     *    rather than returning `false`.
-     * @returns An array of arrays of objects of grouped security schemes. The inner array determines and-grouped
+     * @param {boolean} filterInvalid Optional flag that, when set to `true`, filters out invalid/nonexistent security
+     *    schemes, rather than returning `false`.
+     * @returns {Array} An array of arrays of objects of grouped security schemes. The inner array determines and-grouped
      *    security schemes, the outer array determines or-groups.
      */
-    getSecurityWithTypes(filterInvalid?: boolean): (false | (false | {
+    getSecurityWithTypes(filterInvalid?: boolean): Array<false | Array<false | {
+        security: RMOAS.KeyedSecuritySchemeObject;
         type: SecurityType;
-        security: ({
-            _key: string;
-            'x-default'?: string | number;
-        } & OpenAPIV3.HttpSecurityScheme) | ({
-            _key: string;
-            'x-default'?: string | number;
-        } & OpenAPIV3.ApiKeySecurityScheme) | ({
-            _key: string;
-            'x-default'?: string | number;
-        } & OpenAPIV3.OAuth2SecurityScheme);
-    })[])[];
+    }>>;
     /**
      * @returns An object where the keys are unique scheme types, and the values are arrays containing each security
      *    scheme of that type.
      */
-    prepareSecurity(): Record<SecurityType, RMOAS.KeyedSecuritySchemeObject[]>;
-    getHeaders(): {
-        request: string[];
-        response: string[];
-    };
+    prepareSecurity(): Record<SecurityType, Array<RMOAS.KeyedSecuritySchemeObject>>;
+    getHeaders(): Operation['headers'];
     /**
-     * @returns If the operation has an `operationId` present in its schema.
+     * Determine if the operation has an operation present in its schema.
+     *
+     * @returns {boolean}
      */
     hasOperationId(): boolean;
     /**
-     * Retrieve an operation ID for this operation. If one is not present (it's not required by the spec!) a hash of the
-     * path and method will be returned instead.
+     * Get an `operationId` for this operation. If one is not present (it's not required by the spec!) a hash of the path
+     * and method will be returned instead.
      *
-     * @returns The found or generated operation ID.
+     * @returns {string}
      */
     getOperationId(): string;
     /**
-     * @returns An array of all tags, and their metadata, that exist on this operation.
+     * Return an array of all tags, and their metadata, that exist on this operation.
+     *
+     * @returns {Array}
      */
-    getTags(): OpenAPIV3.TagObject[];
+    getTags(): Array<RMOAS.TagObject>;
     /**
-     * @returns If the operation is flagged as `deprecated` or not.
+     * Return is the operation is flagged as `deprecated` or not.
+     *
+     * @returns {boolean}
      */
     isDeprecated(): boolean;
     /**
+     * Return the parameters (non-request body) on the operation.
+     *
      * @todo This should also pull in common params.
-     * @returns The parameters (non-request body) on the operation.
+     * @returns {Array}
      */
-    getParameters(): OpenAPIV3.ParameterObject[];
+    getParameters(): Array<RMOAS.ParameterObject>;
     /**
      * Convert the operation into an array of JSON Schema for each available type of parameter available on the operation.
-     * `globalDefaults` contains an object of user defined parameter defaults used.
+     * `globalDefaults` contains an object of user defined parameter defaults used in `constructSchema`.
      *
-     * @param globalDefaults An object of global defaults to apply as a `default` in the returned JSON Schema.
-     * @returns An array of JSON Schema objects.
+     * @param {Object} globalDefaults
+     * @returns {Array}
      */
-    getParametersAsJsonSchema(globalDefaults?: unknown): array<object>;
+    getParametersAsJsonSchema(globalDefaults?: unknown): import("./operation/get-parameters-as-json-schema").SchemaWrapper[];
     /**
      * Get a single response for this status code, formatted as JSON schema.
      *
-     * @param statusCode Status code to pull a JSON Schema object for.
-     * @returns A JSON Schema object for the specified response.
+     * @param {string|number} statusCode
+     * @returns {Array}
      */
     getResponseAsJsonSchema(statusCode: string): {
-        type: any;
-        schema: any;
+        type: string | string[];
+        schema: RMOAS.SchemaObject;
         label: string;
+        description?: string;
     }[];
     /**
-     * @returns An array of all valid response status codes for this operation.
+     * Get an array of all valid response status codes for this operation.
+     *
+     * @returns {Array}
      */
-    getResponseStatusCodes(): string[];
+    getResponseStatusCodes(): Array<string>;
     /**
-     * @returns If the operation has a request body.
+     * Determine if the operation has a request body.
+     *
+     * @returns {boolean}
      */
     hasRequestBody(): boolean;
     /**
-     * @returns An array of request body examples that this operation has.
+     * Retrieve an array of request body examples that this operation has.
+     *
+     * @returns {Array}
      */
     getRequestBodyExamples(): RequestBodyExamples;
     /**
-     * @param statusCode HTTP status code to get.
-     * @returns A specific response out of the operation by a given HTTP status code.
+     * Return a specific response out of the operation by a given HTTP status code.
+     *
+     * @param {(string|number)} statusCode
+     * @returns {(boolean|object)}
      */
-    getResponseByStatusCode(statusCode: string | number): false | OpenAPIV3.ResponseObject | OpenAPIV3_1.ResponseObject;
+    getResponseByStatusCode(statusCode: string | number): boolean | RMOAS.ResponseObject;
     /**
-     * @returns An array of response examples that this operation has.
+     * Retrieve an array of response examples that this operation has.
+     *
+     * @returns {Array}
      */
     getResponseExamples(): ResponseExamples;
     /**
-     * @returns If the operation has callbacks.
+     * Determine if the operation has callbacks.
+     *
+     * @returns {boolean}
      */
     hasCallbacks(): boolean;
     /**
@@ -164,15 +171,19 @@ export default class Operation {
      * @param identifier Callback identifier to look for.
      * @param expression Callback expression to look for.
      * @param method HTTP Method on the callback to look for.
-     * @returns The found callback.
+     * @returns {(false|Callback)}
      */
     getCallback(identifier: string, expression: string, method: RMOAS.HttpMethods): false | Callback;
     /**
-     * @returns An array of operations created from each callback.
+     * Retrieve an array of operations created from each callback.
+     *
+     * @returns {Array}
      */
-    getCallbacks(): false | (false | Callback)[];
+    getCallbacks(): false | Array<false | Callback>;
     /**
-     * @returns An array of callback examples that this operation has.
+     * Retrieve an array of callback examples that this operation has.
+     *
+     * @returns {Array}
      */
     getCallbackExamples(): CallbackExamples;
     /**
@@ -195,12 +206,17 @@ export default class Operation {
     getExtension(extension: string): unknown;
 }
 export declare class Callback extends Operation {
+    /**
+     * The identifier that this callback is set to.
+     */
     identifier: string;
-    constructor(api: RMOAS.OASDocument, path: string, method: RMOAS.HttpMethods, operation: RMOAS.OperationObject, identifier: string);
+    constructor(oas: RMOAS.OASDocument, path: string, method: RMOAS.HttpMethods, operation: RMOAS.OperationObject, identifier: string);
     /**
+     * Return the primary identifier for this callback.
+     *
      * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#callback-object}
      * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject}
-     * @returns The primary identifier for this callback.
+     * @returns {string}
      */
     getIdentifier(): string;
 }

package/@types/rmoas.types.d.ts

@@ -5,6 +5,11 @@ import type { JSONSchema4, JSONSchema6, JSONSchema7 } from 'json-schema';
  * @returns If the supplied data has a `$ref` pointer.
  */
 export declare function isRef(check: unknown): check is OpenAPIV3.ReferenceObject | OpenAPIV3_1.ReferenceObject;
+/**
+ * @param check API definition to determine if it's a 3.1 definition.
+ * @returns If the definition is a 3.1 definition.
+ */
+export declare function isOAS31(check: OpenAPIV3.Document | OpenAPIV3_1.Document): check is OpenAPIV3_1.Document;
 export interface User {
     [key: string]: unknown;
     keys?: Array<{
@@ -92,6 +97,11 @@ export declare type ExampleObject = OpenAPIV3.ExampleObject | OpenAPIV3_1.Exampl
  * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#tagObject}
  */
 export declare type TagObject = OpenAPIV3.TagObject | OpenAPIV3_1.TagObject;
+/**
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#headerObject}
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#headerObject}
+ */
+export declare type HeaderObject = OpenAPIV3.HeaderObject | OpenAPIV3_1.HeaderObject;
 /**
  * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#schemaObject}
  * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject}
@@ -101,7 +111,19 @@ export declare type SchemaObject = (OpenAPIV3.SchemaObject | OpenAPIV3_1.SchemaO
     readOnly?: boolean;
     writeOnly?: boolean;
     'x-readme-ref-name'?: string;
+    example?: unknown;
+    examples?: Array<unknown>;
+    nullable?: boolean;
+    xml?: unknown;
+    externalDocs?: unknown;
+    components?: OpenAPIV3_1.ComponentsObject;
 };
+/**
+ * @param check JSON Schema object to determine if it's a non-polymorphic schema.
+ * @param isPolymorphicAllOfChild If this JSON Schema object is the child of a polymorphic `allOf`.
+ * @returns If the JSON Schema object is a JSON Schema object.
+ */
+export declare function isSchema(check: unknown, isPolymorphicAllOfChild?: boolean): check is SchemaObject;
 /**
  * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#securitySchemeObject}
  * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securitySchemeObject}

package/@types/utils.d.ts

@@ -4,12 +4,8 @@ declare const _default: {
     findSchemaDefinition: typeof findSchemaDefinition;
     getSchema: typeof getSchema;
     jsonSchemaTypes: {
-        path: string;
-        query: string;
-        body: string;
-        cookie: string;
-        formData: string;
-        header: string;
+        [key: string]: string;
+        [key: number]: string;
     };
     matchesMimeType: {
         formUrlEncoded: (mimeType: string) => boolean;

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 17.3.0 (2021-12-06)
+
+* feat: OAS 3.1 for JSON Schemas (#530) ([91475da](https://github.com/readmeio/oas/commit/91475da)), closes [#530](https://github.com/readmeio/oas/issues/530)
+
+
+
 ## 17.2.0 (2021-12-02)
 
 * chore(deps-dev): bump @commitlint/cli from 14.1.0 to 15.0.0 (#552) ([b03dbd3](https://github.com/readmeio/oas/commit/b03dbd3)), closes [#552](https://github.com/readmeio/oas/issues/552)