feat: adding openapi-v3

CODEOWNERS

@@ -18,6 +18,7 @@ packages/metadata/* @raymondfeng
 packages/openapi-spec/*  @bajtos @jannyHou
 packages/openapi-spec-builder/* @bajtos @raymondfeng
 packages/openapi-v2/* @jannyHou
+packages/openapi-v3/* @jannyHou
 packages/openapi-v3-types/* @jannyHou
 packages/repository/* @raymondfeng @kjdelisle
 packages/repository-json-schema/* @shimks

MONOREPO.md

@@ -20,6 +20,7 @@ The [loopback-next](https://github.com/strongloop/loopback-next) repository uses
 |[openapi-spec-builder](packages/openapi-spec-builder)      |@loopback/openapi-spec-builder  | Builders to create OpenAPI (Swagger) specification documents in tests |
 |[openapi-spec](packages/openapi-spec)                      |@loopback/openapi-spec          | TypeScript type definitions for OpenAPI Spec/Swagger documents |
 |[openapi-v2](packages/openapi-v2)                          |@loopback/openapi-v2            | Decorators that annotate LoopBack artifacts with OpenAPI v2 (Swagger) metadata and utilities that transform LoopBack metadata to OpenAPI v2 (Swagger) specifications|
+|[openapi-v3](packages/openapi-v3)                          |@loopback/openapi-v3            | Decorators that annotate LoopBack artifacts with OpenAPI v3 metadata and utilities that transform LoopBack metadata to OpenAPI v3 specifications|
 |[openapi-v3-types](packages/openapi-v3-types)              |@loopback/openapi-v3-types      | TypeScript type definitions for OpenAPI Specifications |
 |[repository-json-schema](packages/repository-json-schema)  |@loopback/repository-json-schema| Convert a TypeScript class/model to a JSON Schema |
 |[repository](packages/repository)                          |@loopback/repository            | Define and implement a common set of interfaces for interacting with databases|

packages/openapi-v3-types/src/openapi-v3-spec-types.ts

@@ -258,6 +258,13 @@ export interface MapObject<T> {
   [name: string]: T;
 }
 
+/**
+ * Schemas Object in components
+ */
+export interface SchemasObject extends MapObject<SchemaObject> {
+  [name: string]: SchemaObject;
+}
+
 /**
  * Lists the available scopes for an OAuth2 security scheme.
  */

packages/openapi-v3/LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) IBM Corp. 2018. All Rights Reserved.
+Node module: @loopback/openapi-v3
+This project is licensed under the MIT License, full text below.
+
+--------
+
+MIT license
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

packages/openapi-v3/README.md

@@ -0,0 +1,88 @@
+@loopback/openapi-v3
+
+This package contains:
+
+* Decorators that describe LoopBack artifacts as OpenAPI 3.0.0 metadata.
+* Utilities that transfer LoopBack metadata to OpenAPI 3.0.0 specifications.
+
+## Overview
+
+The package has functions described above for LoopBack controller classes.
+Decorators apply REST api mapping metadata to controller classes and their members. And utilities that inspect controller classes to build OpenAPI 3.0.0 specifications from REST API mapping metadata.
+
+Functions for more artifacts will be added when we need.
+
+## Installation
+
+```
+$ npm install --save @loopback/openapi-v3
+```
+
+## Basic use
+
+Currently this package only has spec generator for controllers.
+It generates OpenAPI specifications for a given decorated controller class, including
+`paths`, `components.schemas`, and `servers`.
+
+Here is an example of calling function `getControllerSpec` to generate the OpenAPI spec:
+
+```js
+import {api, getControllerSpec} from '@loopback/openapi-v3';
+
+@api(somePathSpec)
+class MyController {
+  greet() {
+    return 'Hello world!';
+  }
+}
+
+const myControllerSpec = getControllerSpec(MyController);
+```
+
+then the `myControllerSpec` will be:
+
+```js
+{
+    openapi: '3.0.0',
+    info: { title: 'LoopBack Application', version: '1.0.0' },
+    paths: {
+        '/greet': {
+            get: {
+                responses:  {
+                    '200': {
+                        description: 'The string result.',
+                        schema: { type: 'string' }
+                    }
+                },
+                'x-operation-name': 'greet'
+            }
+        }
+    },
+    servers: [
+        {url: '/'}
+    ]
+}
+```
+
+For details of how to apply controller decorators, please check http://loopback.io/doc/en/lb4/Decorators.html#route-decorators
+
+## Related resources
+
+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).
+
+# Tests
+
+run `npm test` from the root folder.
+
+# Contributors
+
+See [all contributors](https://github.com/strongloop/loopback-next/graphs/contributors).
+
+# License
+
+MIT

packages/openapi-v3/docs.json

@@ -0,0 +1,14 @@
+{
+  "content": [
+    "src/api-decorator.ts",
+    "src/controller-spec.ts",
+    "src/generate-schema.ts",
+    "src/index.ts",
+    "src/json-to-schema.ts",
+    "src/keys.ts",
+    "src/operation-decorator.ts",
+    "src/parameter-decorator.ts",
+    "src/request-body-decorator.ts"
+  ],
+  "codeSectionDepth": 6
+}

packages/openapi-v3/index.d.ts

@@ -0,0 +1,6 @@
+// Copyright IBM Corp. 2018. All Rights Reserved.
+// Node module: @loopback/openapi-v3
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+export * from './dist';

packages/openapi-v3/index.js

@@ -0,0 +1,6 @@
+// Copyright IBM Corp. 2018. All Rights Reserved.
+// Node module: @loopback/openapi-v3
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+module.exports = require('./dist');

packages/openapi-v3/index.ts

@@ -0,0 +1,8 @@
+// Copyright IBM Corp. 2018. All Rights Reserved.
+// Node module: @loopback/openapi-v3
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+// DO NOT EDIT THIS FILE
+// Add any aditional (re)exports to src/index.ts instead.
+export * from './src';

packages/openapi-v3/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@loopback/openapi-v3",
+  "version": "0.1.0",
+  "description": "Processes openapi v3 related metadata",
+  "engines": {
+    "node": ">=8"
+  },
+  "devDependencies": {
+    "@loopback/build": "^0.1.1",
+    "@loopback/openapi-spec-builder": "^0.1.1",
+    "@loopback/repository": "^0.1.1",
+    "@loopback/testlab": "^0.1.1",
+    "@types/debug": "0.0.30",
+    "@types/lodash": "^4.14.96"
+  },
+  "scripts": {
+    "build": "lb-tsc es2017",
+    "build:apidocs": "lb-apidocs",
+    "clean": "lb-clean loopback-openapi-v3*.tgz dist* package",
+    "integration": "lb-mocha \"DIST/test/integration/**/*.js\"",
+    "prepublishOnly": "npm run build && npm run build:apidocs",
+    "pretest": "npm run build",
+    "test": "lb-mocha \"DIST/test/unit/**/*.js\" \"DIST/test/integration/**/*.js\"",
+    "unit": "lb-mocha \"DIST/test/unit/**/*.js\"",
+    "verify": "npm pack && tar xf loopback-openapi-v3*.tgz && tree package && npm run clean"
+  },
+  "author": "IBM",
+  "copyright.owner": "IBM Corp.",
+  "license": "MIT",
+  "keywords": [
+    "Swagger",
+    "OpenAPI Spec",
+    "TypeScript"
+  ],
+  "files": [
+    "README.md",
+    "index.js",
+    "index.d.ts",
+    "dist/src",
+    "api-docs",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/strongloop/loopback-next.git"
+  },
+  "dependencies": {
+    "@loopback/context": "^0.1.1",
+    "@loopback/openapi-v3-types": "^0.1.1",
+    "@loopback/repository-json-schema": "^0.1.1",
+    "debug": "^3.1.0",
+    "lodash": "^4.17.4"
+  }
+}

packages/openapi-v3/src/api-decorator.ts

@@ -0,0 +1,32 @@
+// Copyright IBM Corp. 2018. All Rights Reserved.
+// Node module: @loopback/openapi-v3
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import {ControllerSpec} from './controller-spec';
+import {ClassDecoratorFactory} from '@loopback/context';
+import {OAI3Keys} from './keys';
+
+/**
+ * Decorate the given Controller constructor with metadata describing
+ * the HTTP/REST API the Controller implements/provides.
+ *
+ * `@api` can be applied to controller classes. For example,
+ * ```
+ * @api({basePath: '/my'})
+ * class MyController {
+ *   // ...
+ * }
+ * ```
+ *
+ * @param spec OpenAPI specification describing the endpoints
+ * handled by this controller
+ *
+ * @decorator
+ */
+export function api(spec: ControllerSpec) {
+  return ClassDecoratorFactory.createDecorator<ControllerSpec>(
+    OAI3Keys.CLASS_KEY,
+    spec,
+  );
+}