@digitalroute/bagger - npm Package Compare versions

Comparing version 2.4.5 to 2.4.6

dist/bagger.es5.js

@@ -365,7 +365,7 @@ import { parse } from 'content-type';
      * Content describes the content of a body.
-     * @param contentType The media type of the content. Like 'application/json' or 'text/plain'. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types for more information
+     * @param mediaType The media type of the content. Like 'application/json' or 'text/plain'. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types for more information
      * @param schema A `hapi/joi` schema describing the content of the body. This can also be used for validating requests in run time by using `.getSchema()`.
      */
-    BaggerRequestBody.prototype.content = function (contentType, schema) {
-        this._content.add(contentType, schema);
+    BaggerRequestBody.prototype.content = function (mediaType, schema) {
+        this._content.add(mediaType, schema);
         return this;
@@ -2303,2 +2303,13 @@ };
     };
+    /**
+     * [RFC 3986](https://tools.ietf.org/html/rfc3986#section-2.2) defines a set of reserved characters `:/?#[]@!$&'()*+,;=` that are used as URI component delimiters.
+     * When these characters need to be used literally in a query parameter value, they are usually percent-encoded.
+     * For example, `/` is encoded as `%2F` (or `%2f`), so that the parameter value `quotes/h2g2.txt` would be sent as:
+     *
+     * ```
+     * GET /file?path=quotes%2Fh2g2.txt
+     * ```
+     *
+     * @param allowReserved If you want a query parameter that is not percent-encoded, set allowReserved to `true`.
+     */
     BaggerParameter.prototype.allowReserved = function (allowReserved) {
@@ -2308,2 +2319,9 @@ this.settings.allowReserved = allowReserved;
     };
+    /**
+     * To describe the parameter contents, you can use either the `schema()` or `addContent()` method.
+     * They are mutually exclusive and used in different scenarios. In most cases, you would use `schema()`.
+     * It lets you describe primitive values, as well as simple arrays and objects serialized into a string.
+     * The serialization method for array and object parameters is defined by the `style()` and `explode() methods used in that parameter.
+     * @param schema Describes the format of the parameter. Bagger uses joi schemas and translates them into OpenAPI 3 schemas.
+     */
     BaggerParameter.prototype.schema = function (schema) {
@@ -2316,2 +2334,8 @@ if (Object.keys(this._content.getSchemas()).length > 0) {
     };
+    /**
+     * You can add examples to parameters to make OpenAPI specification of your web service clearer.
+     * Examples can be read by tools and libraries that process your API in some way.
+     * For example, an API mocking tool can use sample values to generate mock requests.
+     * @param examples An object with Joi.Schema ([link](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/b8183c0147e7412a4e0414a5456441789473b4d8/types/hapi__joi/index.d.ts#L304))
+     */
     BaggerParameter.prototype.examples = function (examples) {
@@ -2321,9 +2345,36 @@ this.settings.examples = examples;
     };
-    BaggerParameter.prototype.addContent = function (contentType, schema) {
+    /**
+     * To describe the parameter contents, you can use either the `schema()` or `addContent()` method.
+     * They are mutually exclusive and used in different scenarios. In most cases, you would use `schema()`.
+     * `addContent()` is used in complex serialization scenarios that are not covered by `style()` and `explode()`.
+     * For example, if you need to send a JSON string in the query string like so:
+     *
+     * ```
+     * filter={"type":"t-shirt","color":"blue"}
+     * ```
+     *
+     * In this case you need to define the schema by using `addContent()` like this:
+     *
+     * ```js
+     * const joi = require('@hapi/joi')
+     * parameter.addContent('application/json', joi.object().keys({
+     *  type: joi.string(),
+     *  color: joi.string()
+     * }))
+     * ```
+     *
+     * @param mediaType The media type of the body. Like 'application/json'
+     * @param schema Describes the format of the parameter. Bagger uses joi schemas and translates them into OpenAPI 3 schemas.
+     */
+    BaggerParameter.prototype.addContent = function (mediaType, schema) {
         if (this.settings.schema) {
             throw new BaggerSchemaDefinedForParameterError();
         }
-        this._content.add(contentType, schema);
+        this._content.add(mediaType, schema);
         return this;
     };
+    /**
+     * Returns the schema if there exists a schema.
+     * @return `{ 'application/json': schema }`
+     */
     BaggerParameter.prototype.getSchemas = function () {
@@ -2330,0 +2381,0 @@ if (this._schema) {

dist/parameters.js

@@ -104,2 +104,13 @@ "use strict";
     };
+    /**
+     * [RFC 3986](https://tools.ietf.org/html/rfc3986#section-2.2) defines a set of reserved characters `:/?#[]@!$&'()*+,;=` that are used as URI component delimiters.
+     * When these characters need to be used literally in a query parameter value, they are usually percent-encoded.
+     * For example, `/` is encoded as `%2F` (or `%2f`), so that the parameter value `quotes/h2g2.txt` would be sent as:
+     *
+     * ```
+     * GET /file?path=quotes%2Fh2g2.txt
+     * ```
+     *
+     * @param allowReserved If you want a query parameter that is not percent-encoded, set allowReserved to `true`.
+     */
     BaggerParameter.prototype.allowReserved = function (allowReserved) {
@@ -109,2 +120,9 @@ this.settings.allowReserved = allowReserved;
     };
+    /**
+     * To describe the parameter contents, you can use either the `schema()` or `addContent()` method.
+     * They are mutually exclusive and used in different scenarios. In most cases, you would use `schema()`.
+     * It lets you describe primitive values, as well as simple arrays and objects serialized into a string.
+     * The serialization method for array and object parameters is defined by the `style()` and `explode() methods used in that parameter.
+     * @param schema Describes the format of the parameter. Bagger uses joi schemas and translates them into OpenAPI 3 schemas.
+     */
     BaggerParameter.prototype.schema = function (schema) {
@@ -117,2 +135,8 @@ if (Object.keys(this._content.getSchemas()).length > 0) {
     };
+    /**
+     * You can add examples to parameters to make OpenAPI specification of your web service clearer.
+     * Examples can be read by tools and libraries that process your API in some way.
+     * For example, an API mocking tool can use sample values to generate mock requests.
+     * @param examples An object with Joi.Schema ([link](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/b8183c0147e7412a4e0414a5456441789473b4d8/types/hapi__joi/index.d.ts#L304))
+     */
     BaggerParameter.prototype.examples = function (examples) {
@@ -122,9 +146,36 @@ this.settings.examples = examples;
     };
-    BaggerParameter.prototype.addContent = function (contentType, schema) {
+    /**
+     * To describe the parameter contents, you can use either the `schema()` or `addContent()` method.
+     * They are mutually exclusive and used in different scenarios. In most cases, you would use `schema()`.
+     * `addContent()` is used in complex serialization scenarios that are not covered by `style()` and `explode()`.
+     * For example, if you need to send a JSON string in the query string like so:
+     *
+     * ```
+     * filter={"type":"t-shirt","color":"blue"}
+     * ```
+     *
+     * In this case you need to define the schema by using `addContent()` like this:
+     *
+     * ```js
+     * const joi = require('@hapi/joi')
+     * parameter.addContent('application/json', joi.object().keys({
+     *  type: joi.string(),
+     *  color: joi.string()
+     * }))
+     * ```
+     *
+     * @param mediaType The media type of the body. Like 'application/json'
+     * @param schema Describes the format of the parameter. Bagger uses joi schemas and translates them into OpenAPI 3 schemas.
+     */
+    BaggerParameter.prototype.addContent = function (mediaType, schema) {
         if (this.settings.schema) {
             throw new BaggerSchemaDefinedForParameterError();
         }
-        this._content.add(contentType, schema);
+        this._content.add(mediaType, schema);
         return this;
     };
+    /**
+     * Returns the schema if there exists a schema.
+     * @return `{ 'application/json': schema }`
+     */
     BaggerParameter.prototype.getSchemas = function () {
@@ -131,0 +182,0 @@ if (this._schema) {

dist/request_body.js

@@ -48,7 +48,7 @@ "use strict";
      * Content describes the content of a body.
-     * @param contentType The media type of the content. Like 'application/json' or 'text/plain'. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types for more information
+     * @param mediaType The media type of the content. Like 'application/json' or 'text/plain'. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types for more information
      * @param schema A `hapi/joi` schema describing the content of the body. This can also be used for validating requests in run time by using `.getSchema()`.
      */
-    BaggerRequestBody.prototype.content = function (contentType, schema) {
-        this._content.add(contentType, schema);
+    BaggerRequestBody.prototype.content = function (mediaType, schema) {
+        this._content.add(mediaType, schema);
         return this;
@@ -55,0 +55,0 @@ };

dist/types/parameters.d.ts

@@ -58,6 +58,57 @@ import { ParameterObject, ParameterStyle, ReferenceObject, ExampleObject } from 'openapi3-ts';
     explode(explode: boolean): BaggerParameter;
+    /**
+     * [RFC 3986](https://tools.ietf.org/html/rfc3986#section-2.2) defines a set of reserved characters `:/?#[]@!$&'()*+,;=` that are used as URI component delimiters.
+     * When these characters need to be used literally in a query parameter value, they are usually percent-encoded.
+     * For example, `/` is encoded as `%2F` (or `%2f`), so that the parameter value `quotes/h2g2.txt` would be sent as:
+     *
+     * ```
+     * GET /file?path=quotes%2Fh2g2.txt
+     * ```
+     *
+     * @param allowReserved If you want a query parameter that is not percent-encoded, set allowReserved to `true`.
+     */
     allowReserved(allowReserved: boolean): BaggerParameter;
+    /**
+     * To describe the parameter contents, you can use either the `schema()` or `addContent()` method.
+     * They are mutually exclusive and used in different scenarios. In most cases, you would use `schema()`.
+     * It lets you describe primitive values, as well as simple arrays and objects serialized into a string.
+     * The serialization method for array and object parameters is defined by the `style()` and `explode() methods used in that parameter.
+     * @param schema Describes the format of the parameter. Bagger uses joi schemas and translates them into OpenAPI 3 schemas.
+     */
     schema(schema: Schema): BaggerParameter;
+    /**
+     * You can add examples to parameters to make OpenAPI specification of your web service clearer.
+     * Examples can be read by tools and libraries that process your API in some way.
+     * For example, an API mocking tool can use sample values to generate mock requests.
+     * @param examples An object with Joi.Schema ([link](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/b8183c0147e7412a4e0414a5456441789473b4d8/types/hapi__joi/index.d.ts#L304))
+     */
     examples(examples: ExamplesObject): BaggerParameter;
-    addContent(contentType: string, schema: Schema): BaggerParameter;
+    /**
+     * To describe the parameter contents, you can use either the `schema()` or `addContent()` method.
+     * They are mutually exclusive and used in different scenarios. In most cases, you would use `schema()`.
+     * `addContent()` is used in complex serialization scenarios that are not covered by `style()` and `explode()`.
+     * For example, if you need to send a JSON string in the query string like so:
+     *
+     * ```
+     * filter={"type":"t-shirt","color":"blue"}
+     * ```
+     *
+     * In this case you need to define the schema by using `addContent()` like this:
+     *
+     * ```js
+     * const joi = require('@hapi/joi')
+     * parameter.addContent('application/json', joi.object().keys({
+     *  type: joi.string(),
+     *  color: joi.string()
+     * }))
+     * ```
+     *
+     * @param mediaType The media type of the body. Like 'application/json'
+     * @param schema Describes the format of the parameter. Bagger uses joi schemas and translates them into OpenAPI 3 schemas.
+     */
+    addContent(mediaType: string, schema: Schema): BaggerParameter;
+    /**
+     * Returns the schema if there exists a schema.
+     * @return `{ 'application/json': schema }`
+     */
     getSchemas(): ContentSchemas;
@@ -64,0 +115,0 @@ compile(): ParameterObject;

dist/types/request_body.d.ts

@@ -22,6 +22,6 @@ import { ContentSchemas } from './content';
      * Content describes the content of a body.
-     * @param contentType The media type of the content. Like 'application/json' or 'text/plain'. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types for more information
+     * @param mediaType The media type of the content. Like 'application/json' or 'text/plain'. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types for more information
      * @param schema A `hapi/joi` schema describing the content of the body. This can also be used for validating requests in run time by using `.getSchema()`.
      */
-    content(contentType: string, schema: Schema): BaggerRequestBody;
+    content(mediaType: string, schema: Schema): BaggerRequestBody;
     /**
@@ -28,0 +28,0 @@ * Get the `hapi/joi` schemas that is used to describe the body content. It can be used for validating requests in runtime.

package.json

 {
   "name": "@digitalroute/bagger",
-  "version": "2.4.5",
+  "version": "2.4.6",
   "description": "🎒 A joi-compatible tool for building swagger definitions",
@@ -5,0 +5,0 @@ "main": "dist/bagger.umd.js",

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

265352

increased by4.58%

Lines of code

8396

increased by2.49%

No dependency changes