@loopback/openapi-spec-builder 4.0.0-alpha.6 → 4.0.0

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) IBM Corp. 2013,2017. All Rights Reserved.
+Copyright (c) IBM Corp. 2017,2019.
 Node module: @loopback/openapi-spec-builder
 This project is licensed under the MIT License, full text below.
 

package/README.md

@@ -1,82 +1,111 @@
 # @loopback/openapi-spec-builder
 
-Make it easy to create OpenAPI (Swagger) specification documents in your
-tests using the builder pattern.
+Make it easy to create OpenAPI specification documents in your tests using the
+builder pattern.
 
 ## Overview
 
 Creating a full OpenAPI spec document in automated tests is rather cumbersome,
-long JSON-like objects pollute the test test code and make it difficult
-for readers to distinguish between what's important in the test and what's just
-shared swagger boilerplate.
+long JSON-like objects pollute the test test code and make it difficult for
+readers to distinguish between what's important in the test and what's just
+shared OpenAPI boilerplate.
 
 OpenApiSpecBuilder utilizes
-[Test Data Builder pattern](http://www.natpryce.com/articles/000714.html)
-to provide a TypeScript/JavaScript API allowing users to create
-full OpenAPI Spec documents in few lines of code.
+[Test Data Builder pattern](http://www.natpryce.com/articles/000714.html) to
+provide a TypeScript/JavaScript API allowing users to create full OpenAPI Spec
+documents in few lines of code.
 
 ## Installation
 
-```shell
-$ npm install --save-dev @loopback/openapi-spec-builder
+```sh
+npm install --save-dev @loopback/openapi-spec-builder
 ```
 
-_This package is typically used in tests, save it to `devDependencies` via `--save-dev`._
+_This package is typically used in tests, save it to `devDependencies` via
+`--save-dev`._
 
 ## Basic use
 
 ```ts
-import {givenOpenApiSpec, OpenApiSpecBuilder} from '@loopback/openapi-spec-builder';
+import {
+  anOpenApiSpec,
+  OpenApiSpecBuilder,
+} from '@loopback/openapi-spec-builder';
 
-const spec = givenOpenApiSpec()
+const spec = anOpenApiSpec()
   .withOperationReturningString('get', '/hello', 'greet')
   .build();
 
 // which is equivalent to the following longer form
-
 const spec = new OpenApiSpecBuilder()
   .withOperation('get', '/hello', {
     'x-operation-name': 'greet',
     responses: {
-      '200': { type: 'string' },
+      '200': {
+        description: 'The string result.',
+        content: {
+          'text/plain': {
+            schema: {
+              type: 'string',
+            },
+          },
+        },
+      },
     },
   })
   .build();
 
 // the spec
-
 const spec = {
-  basePath: '/',
+  openapi: '3.0.0',
+  info: {title: 'LoopBack Application', version: '1.0.0'},
+  servers: [
+    {
+      url: '/',
+    },
+  ],
   paths: {
     '/hello': {
       get: {
         'x-operation-name': 'greet',
         responses: {
-          '200': { type: 'string' },
+          '200': {
+            description: 'The string result.',
+            content: {
+              'text/plain': {
+                schema: {
+                  type: 'string',
+                },
+              },
+            },
+          },
         },
-      }
-    }
-  }
+      },
+    },
+  },
 };
 ```
 
 ## Related resources
 
-See https://www.openapis.org/ and [version 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md)
+See <https://www.openapis.org/> and
+[version 3.0.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md)
 of OpenAPI Specification.
 
 ## Contributions
 
-IBM/StrongLoop is an active supporter of open source and welcomes contributions to our projects as well as those of the Node.js community in general. For more information on how to contribute please refer to the [Contribution Guide](https://loopback.io/doc/en/contrib/index.html).
+- [Guidelines](https://github.com/loopbackio/loopback-next/blob/master/docs/CONTRIBUTING.md)
+- [Join the team](https://github.com/loopbackio/loopback-next/issues/110)
 
-# Tests
+## Tests
 
-run `npm test` from the root folder.
+Run `npm test` from the root folder.
 
-# Contributors
+## Contributors
 
-See [all contributors](https://github.com/strongloop/loopback-next/graphs/contributors).
+See
+[all contributors](https://github.com/loopbackio/loopback-next/graphs/contributors).
 
-# License
+## License
 
 MIT

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A package to simplify creating OpenAPI specification documents in your tests
+ * using the builder pattern.
+ *
+ * @remarks
+ * Creating a full OpenAPI spec document in automated tests is rather
+ * cumbersome, long JSON-like objects pollute the test test code and make it
+ * difficult for readers to distinguish between what's important in the test and
+ * what's just shared OpenAPI boilerplate.
+ *
+ * OpenApiSpecBuilder utilizes
+ * {@link http://www.natpryce.com/articles/000714.html | Test Data Builder pattern}
+ * to provide a TypeScript/JavaScript API allowing users to create full OpenAPI
+ * Specification 3 documents in few lines of code.
+ *
+ * @packageDocumentation
+ */
+export * from './openapi-spec-builder';

package/dist/index.js

@@ -0,0 +1,26 @@
+"use strict";
+// Copyright IBM Corp. 2017,2020. All Rights Reserved.
+// Node module: @loopback/openapi-spec-builder
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+/**
+ * A package to simplify creating OpenAPI specification documents in your tests
+ * using the builder pattern.
+ *
+ * @remarks
+ * Creating a full OpenAPI spec document in automated tests is rather
+ * cumbersome, long JSON-like objects pollute the test test code and make it
+ * difficult for readers to distinguish between what's important in the test and
+ * what's just shared OpenAPI boilerplate.
+ *
+ * OpenApiSpecBuilder utilizes
+ * {@link http://www.natpryce.com/articles/000714.html | Test Data Builder pattern}
+ * to provide a TypeScript/JavaScript API allowing users to create full OpenAPI
+ * Specification 3 documents in few lines of code.
+ *
+ * @packageDocumentation
+ */
+(0, tslib_1.__exportStar)(require("./openapi-spec-builder"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,sDAAsD;AACtD,8CAA8C;AAC9C,+CAA+C;AAC/C,gEAAgE;;;AAEhE;;;;;;;;;;;;;;;;GAgBG;AAEH,sEAAuC"}

package/dist/openapi-spec-builder.d.ts

@@ -0,0 +1,188 @@
+import { CallbackObject, ComponentsObject, ExampleObject, HeaderObject, ISpecificationExtension, LinkObject, OpenAPIObject, OperationObject, ParameterObject, ReferenceObject, RequestBodyObject, ResponseObject, SchemaObject, SecuritySchemeObject } from 'openapi3-ts';
+/**
+ * Create a new instance of OpenApiSpecBuilder.
+ *
+ * @param basePath - The base path on which the API is served.
+ */
+export declare function anOpenApiSpec(): OpenApiSpecBuilder;
+/**
+ * Create a new instance of OperationSpecBuilder.
+ */
+export declare function anOperationSpec(): OperationSpecBuilder;
+/**
+ * Create a new instance of ComponentsSpecBuilder.
+ */
+export declare function aComponentsSpec(): ComponentsSpecBuilder;
+export declare class BuilderBase<T extends ISpecificationExtension> {
+    protected _spec: T;
+    constructor(initialSpec: T);
+    /**
+     * Add a custom (extension) property to the spec object.
+     *
+     * @param key - The property name starting with "x-".
+     * @param value - The property value.
+     */
+    withExtension(key: string, value: any): this;
+    /**
+     * Build the spec object.
+     */
+    build(): T;
+}
+/**
+ * A builder for creating OpenApiSpec documents.
+ */
+export declare class OpenApiSpecBuilder extends BuilderBase<OpenAPIObject> {
+    /**
+     * @param basePath - The base path on which the API is served.
+     */
+    constructor();
+    /**
+     * Define a new OperationObject at the given path and verb (method).
+     *
+     * @param verb - The HTTP verb.
+     * @param path - The path relative to basePath.
+     * @param spec - Additional specification of the operation.
+     */
+    withOperation(verb: string, path: string, spec: OperationObject | OperationSpecBuilder): this;
+    /**
+     * Define a new operation that returns a string response.
+     *
+     * @param verb - The HTTP verb.
+     * @param path - The path relative to basePath.
+     * @param operationName - The name of the controller method implementing
+     * this operation (`x-operation-name` field).
+     */
+    withOperationReturningString(verb: string, path: string, operationName?: string): this;
+    /**
+     * Define a new ComponentsObject.
+     *
+     * @param spec - Specification of the components.
+     */
+    withComponents(spec: ComponentsObject | ComponentsSpecBuilder): this;
+}
+/**
+ * A builder for creating OperationObject specifications.
+ */
+export declare class OperationSpecBuilder extends BuilderBase<OperationObject> {
+    constructor();
+    /**
+     * Describe a response for a given HTTP status code.
+     * @param status - HTTP status code or string "default"
+     * @param responseSpec - Specification of the response
+     */
+    withResponse(status: number | 'default', responseSpec: ResponseObject): this;
+    withStringResponse(status?: number | 'default'): this;
+    /**
+     * Describe one more parameters accepted by the operation.
+     * Note that parameters are positional in OpenAPI Spec, therefore
+     * the first call of `withParameter` defines the first parameter,
+     * the second call defines the second parameter, etc.
+     * @param parameterSpecs
+     */
+    withParameter(...parameterSpecs: ParameterObject[]): this;
+    withRequestBody(requestBodySpec: RequestBodyObject): this;
+    /**
+     * Define the operation name (controller method name).
+     *
+     * @param name - The name of the controller method implementing this operation.
+     */
+    withOperationName(name: string): this;
+    /**
+     * Define the controller name (controller name).
+     *
+     * @param name - The name of the controller containing this operation.
+     */
+    withControllerName(name: string): this;
+    /**
+     * Set up the `operationId` if not configured
+     */
+    private setupOperationId;
+    /**
+     * Define the operationId
+     * @param operationId - Operation id
+     */
+    withOperationId(operationId: string): this;
+    /**
+     * Describe tags associated with the operation
+     * @param tags
+     */
+    withTags(tags: string | string[]): this;
+}
+/**
+ * A builder for creating ComponentsObject specifications.
+ */
+export declare class ComponentsSpecBuilder extends BuilderBase<ComponentsObject> {
+    constructor();
+    /**
+     * Define a component schema.
+     *
+     * @param name - The name of the schema
+     * @param schema - Specification of the schema
+     *
+     */
+    withSchema(name: string, schema: SchemaObject | ReferenceObject): this;
+    /**
+     * Define a component response.
+     *
+     * @param name - The name of the response
+     * @param response - Specification of the response
+     *
+     */
+    withResponse(name: string, response: ResponseObject | ReferenceObject): this;
+    /**
+     * Define a component parameter.
+     *
+     * @param name - The name of the parameter
+     * @param parameter - Specification of the parameter
+     *
+     */
+    withParameter(name: string, parameter: ParameterObject | ReferenceObject): this;
+    /**
+     * Define a component example.
+     *
+     * @param name - The name of the example
+     * @param example - Specification of the example
+     *
+     */
+    withExample(name: string, example: ExampleObject | ReferenceObject): this;
+    /**
+     * Define a component request body.
+     *
+     * @param name - The name of the request body
+     * @param requestBody - Specification of the request body
+     *
+     */
+    withRequestBody(name: string, requestBody: RequestBodyObject | ReferenceObject): this;
+    /**
+     * Define a component header.
+     *
+     * @param name - The name of the header
+     * @param header - Specification of the header
+     *
+     */
+    withHeader(name: string, header: HeaderObject | ReferenceObject): this;
+    /**
+     * Define a component security scheme.
+     *
+     * @param name - The name of the security scheme
+     * @param securityScheme - Specification of the security scheme
+     *
+     */
+    withSecurityScheme(name: string, securityScheme: SecuritySchemeObject | ReferenceObject): this;
+    /**
+     * Define a component link.
+     *
+     * @param name - The name of the link
+     * @param link - Specification of the link
+     *
+     */
+    withLink(name: string, link: LinkObject | ReferenceObject): this;
+    /**
+     * Define a component callback.
+     *
+     * @param name - The name of the callback
+     * @param callback - Specification of the callback
+     *
+     */
+    withCallback(name: string, callback: CallbackObject | ReferenceObject): this;
+}