feat: Create @loopback/openapi-v2 #804

jannyHou · 2017-12-15T21:26:45Z

connect to #753
Replace #800

create a new package openapi-specgen
move route decorators and related test cases from rest to openapi-specgen

I will put more release details after the code looks good.

bajtos · 2018-01-02T15:21:36Z

Since this is mostly moving files around, there is little to review here. The changes look reasonable after a quick review.

My only objection is against the package name @loopback/openapi-specgen - the code here is not generating the spec, it's providing decorators to define the specification. Can we come up with a better name, one that conveys this intent in a better way? Few examples that come to my mind: @loopback/openapi-metadata, @loopback/openapi-decorators. Or perhaps simply @loopback/openapi, meaning "the glue between loopback and openapi-spec".

jannyHou · 2018-01-02T15:31:52Z

@bajtos Thanks for review, this package will contain all of the openapi spec generation code, like function getControllerSpec, not only the route decorators.

Functions like getModelMetadata in PR #813 will be moved to this repo as well.

shimks

LGTM

raymondfeng · 2018-01-02T17:30:55Z

@jannyHou The module is the home for openapi related metadata, including decorators for describing the metadata and utility methods for inspecting the metadata. It makes sense to me to name it as @loopback/openapi or @loopback/openapi-metadata.

jannyHou · 2018-01-02T18:15:36Z

including decorators for describing the metadata and utility methods for inspecting the metadata

That's true, specgen doesn't imply it contains decorators for describing the metadata.

And I prefer @loopback/openapi

@raymondfeng I had a talk with @kjdelisle, we think at this moment @loopback/openapi-v2 would be a good name for it, it specifies the version, and we can rename it to @loopback/openapi-v3 after upgrading.

raymondfeng · 2018-01-02T20:51:37Z

packages/openapi-v2/README.md

+
+This package contains:
+
+- Decorators that describe LoopBack artifacts as metadata.


Decorators that apply REST api mapping metadata to controller classes and their members.

@raymondfeng as I have mentioned in #804 (comment), my intension to have this package is to organize all the openapi related decorators and spec generation functions together. Not only for controller classes....

@raymondfeng How about "Decorators that describe LoopBack artifacts as openapi metadata."? I missed an important word "openapi" in this commit.

These decorators are created for application developers to describe REST mapping of controller classes, right?

raymondfeng · 2018-01-02T20:54:51Z

packages/openapi-v2/README.md

+This package contains:
+
+- Decorators that describe LoopBack artifacts as metadata.
+- Uilities that tranfer LoopBack remoting metadata to swagger specifications. 


Utilities that inspect controller classes to build OpenAPI v2 (Swagger) specifications from REST api mapping metadata.

raymondfeng · 2018-01-02T21:53:58Z

packages/openapi-v2/README.md

+## 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 v2 (Swagger) specifications from REST api mapping metadata.


Duplicate of the This package contains section?

@raymondfeng There is a difference: the top level description is for ALL artifacts :) And the Overview section says currently what the package has(functions for controller classes). And we will add more for other artifacts if need.

kjdelisle

Almost there! Just need a couple quick fixes:

Rename the openapi-spec package to openapi-v2-spec to make it clear which version of the OpenAPI specification this package is meant to represent.
Add in the missing newlines
Reword the commit message to say feat: Create @loopback/openapi-v2-spec
Bump the minimum engine to 8.

kjdelisle · 2018-01-02T21:51:49Z

packages/openapi-v2/.gitignore

@@ -0,0 +1,3 @@
+*.tgz
+dist*
+package


Missing newline

kjdelisle · 2018-01-02T21:51:59Z

packages/openapi-v2/.npmrc

@@ -0,0 +1 @@
+package-lock=false


kjdelisle · 2018-01-02T21:54:03Z

packages/openapi-v2/package.json

+  "version": "1.0.0-alpha1",
+  "description": "Processes openapi v2 related metadata",
+  "engines": {
+    "node": ">=6"


Please set this to >=8, as we've decided not to support Node 6 for our release.

kjdelisle · 2018-01-02T22:06:11Z

packages/openapi-v2/tsconfig.build.json

+    },
+    "include": ["src", "test"]
+  }
+


b-admike · 2018-01-03T13:01:50Z

packages/openapi-v2/README.md

+This package contains:
+
+- Decorators that describe LoopBack artifacts as OpenAPI v2 (Swagger) metadata.
+- Utilities that tranfer LoopBack metadata to OpenAPI v2 (Swagger) swagger specifications. 


typo: transfer

jannyHou · 2018-01-03T16:06:15Z

Rename the openapi-spec package to openapi-v2-spec

This is out of the scope of this PR and I don't think it's a quick fix. A simple replacement affects 50 files and we also need to check example repos.

I will address it in the next PR(upgrading from v2-->v3)

kjdelisle · 2018-01-03T16:21:00Z

This is out of the scope of this PR and I don't think it's a quick fix. A simple replacement affects 50 files and we also need to check example repos.

Agreed, as long as the newline fixes are put into place, LGTM.

b-admike

raymondfeng · 2018-01-03T16:31:09Z

packages/openapi-v2/package.json

+    "api-docs",
+    "src"
+  ],
+  "repository": {


Please add the following so that the package will be published with public access with npm run release.

"publishConfig": { "access": "public" },

raymondfeng · 2018-01-03T17:37:30Z

Do you want to change the commit message to be feat: create @loopback/openapi-v2?

jannyHou · 2018-01-03T17:40:15Z

@raymondfeng 😀 my bad, forgot to change the commit message.

bajtos · 2018-01-05T08:40:00Z

packages/authentication/package.json

@@ -25,6 +25,7 @@
  "dependencies": {
    "@loopback/context": "^4.0.0-alpha.24",
    "@loopback/core": "^4.0.0-alpha.26",
+    "@loopback/openapi-v2": "1.0.0-alpha1",


@jannyHou The version number should have been 1.0.0-alpha.1 (notice the dot between "alpha" and "1"), this is the scheme we are using in other packages (look at lines 26 and 27 above for examples).

I think Raymond already created a PR to fix the version.

jannyHou requested review from bajtos, kjdelisle and raymondfeng as code owners December 15, 2017 21:26

jannyHou added the needs-priority label Dec 15, 2017

jannyHou mentioned this pull request Dec 15, 2017

refactor: Move metadata.ts to openapi-spec[WIP] #800

Closed

2 tasks

jannyHou changed the title ~~feat: Create @loopback/openapi-specgen~~ feat: Create @loopback/openapi-specgen[WIP] Dec 18, 2017

jannyHou mentioned this pull request Dec 18, 2017

[OpenAPI] Switch to OpenAPI v3 for spec and routing #753

Closed

5 tasks

jannyHou force-pushed the openapi-specgen branch 2 times, most recently from fca4e22 to c4b8c94 Compare December 27, 2017 22:18

jannyHou self-assigned this Dec 28, 2017

jannyHou force-pushed the openapi-specgen branch from c4b8c94 to 9c06d96 Compare January 1, 2018 22:24

jannyHou changed the title ~~feat: Create @loopback/openapi-specgen[WIP]~~ feat: Create @loopback/openapi-specgen Jan 1, 2018

shimks approved these changes Jan 2, 2018

View reviewed changes

jannyHou force-pushed the openapi-specgen branch from 9c06d96 to 72b7a9b Compare January 2, 2018 17:06

jannyHou force-pushed the openapi-specgen branch from 5b7ebb7 to 3d8a998 Compare January 2, 2018 20:34

raymondfeng reviewed Jan 2, 2018

View reviewed changes

raymondfeng changed the title ~~feat: Create @loopback/openapi-specgen~~ feat: Create @loopback/openapi-v2 Jan 2, 2018

kjdelisle added review and removed needs-priority labels Jan 2, 2018

raymondfeng reviewed Jan 2, 2018

View reviewed changes

kjdelisle suggested changes Jan 2, 2018

View reviewed changes

b-admike reviewed Jan 3, 2018

View reviewed changes

jannyHou force-pushed the openapi-specgen branch 2 times, most recently from 754044e to 2faaae5 Compare January 3, 2018 16:08

kjdelisle approved these changes Jan 3, 2018

View reviewed changes

b-admike approved these changes Jan 3, 2018

View reviewed changes

raymondfeng reviewed Jan 3, 2018

View reviewed changes

jannyHou force-pushed the openapi-specgen branch from 2faaae5 to d5fde90 Compare January 3, 2018 17:02

feat: create @loopback/openapi-v2

9c59059

jannyHou force-pushed the openapi-specgen branch from d5fde90 to b1b1c73 Compare January 3, 2018 17:39

jannyHou added 4 commits January 3, 2018 12:39

refactor: rename files

cdbc0c4

docs: update readme

e6edd9e

fix: apply feedback

f5e7733

fix: set publishConfig

b1b1c73

raymondfeng approved these changes Jan 3, 2018

View reviewed changes

jannyHou merged commit 4ddd4bc into master Jan 3, 2018

jannyHou removed the review label Jan 3, 2018

jannyHou deleted the openapi-specgen branch January 3, 2018 20:23

bajtos reviewed Jan 5, 2018

View reviewed changes

bajtos mentioned this pull request Jan 5, 2018

build(openapi-v2): fix the test script #840

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Create @loopback/openapi-v2 #804

feat: Create @loopback/openapi-v2 #804

jannyHou commented Dec 15, 2017 •

edited

Loading

bajtos commented Jan 2, 2018

jannyHou commented Jan 2, 2018 •

edited

Loading

shimks left a comment

raymondfeng commented Jan 2, 2018

jannyHou commented Jan 2, 2018 •

edited

Loading

raymondfeng Jan 2, 2018

jannyHou Jan 2, 2018

jannyHou Jan 2, 2018

raymondfeng Jan 2, 2018

raymondfeng Jan 2, 2018

raymondfeng Jan 2, 2018

jannyHou Jan 2, 2018 •

edited

Loading

kjdelisle left a comment •

edited by jannyHou

Loading

kjdelisle Jan 2, 2018

kjdelisle Jan 2, 2018

kjdelisle Jan 2, 2018

kjdelisle Jan 2, 2018

b-admike Jan 3, 2018

jannyHou commented Jan 3, 2018 •

edited

Loading

kjdelisle commented Jan 3, 2018 •

edited

Loading

b-admike left a comment

raymondfeng Jan 3, 2018

raymondfeng commented Jan 3, 2018

jannyHou commented Jan 3, 2018 •

edited

Loading

bajtos Jan 5, 2018

jannyHou Jan 5, 2018


		This package contains:

		- Decorators that describe LoopBack artifacts as metadata.

@@ @@ -0,0 +1,3 @@ @@
+              *.tgz
+              dist*
+              package

		@@ -0,0 +1 @@
		package-lock=false

feat: Create @loopback/openapi-v2 #804

feat: Create @loopback/openapi-v2 #804

Conversation

jannyHou commented Dec 15, 2017 • edited Loading

bajtos commented Jan 2, 2018

jannyHou commented Jan 2, 2018 • edited Loading

shimks left a comment

Choose a reason for hiding this comment

raymondfeng commented Jan 2, 2018

jannyHou commented Jan 2, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jannyHou Jan 2, 2018 • edited Loading

Choose a reason for hiding this comment

kjdelisle left a comment • edited by jannyHou Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jannyHou commented Jan 3, 2018 • edited Loading

kjdelisle commented Jan 3, 2018 • edited Loading

b-admike left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

raymondfeng commented Jan 3, 2018

jannyHou commented Jan 3, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jannyHou commented Dec 15, 2017 •

edited

Loading

jannyHou commented Jan 2, 2018 •

edited

Loading

jannyHou commented Jan 2, 2018 •

edited

Loading

jannyHou Jan 2, 2018 •

edited

Loading

kjdelisle left a comment •

edited by jannyHou

Loading

jannyHou commented Jan 3, 2018 •

edited

Loading

kjdelisle commented Jan 3, 2018 •

edited

Loading

jannyHou commented Jan 3, 2018 •

edited

Loading