-
Notifications
You must be signed in to change notification settings - Fork 102
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[SEMVER-MAJOR] Generate Swagger Spec 2.0 documentation #115
Conversation
Notable breaking changes: - The swagger output is a single object (JSON response) served at /explorer/swagger.json - Methods with a single return arg without "root:true" flag are expected to produce an object response with a single property now, i.e. `{ data: arg }`. In v1.x, we were treating such arg as if "root:true" was specified. The new behaviour matches the actual implementation in strong-remoting. - The property constraint "length" is translated to "maxLength" now. - `operationId` includes model name now, because ids must be unique - X-Forwarded-* headers are no longer processed, Swagger Spec 2.0 has a way how to specify "use the scheme + host where the doc is served" - opts.omitProtocolInBaseUrl was removed for the same reasons as X-Forwarded-* headers - The deprecated opts.swaggerDistRoot was removed.
@bajtos To add to the list of breaking changes, the way to load the explorer is different now. We should document that and update the yeoman generator. |
// operation ids to be unique, thus we have to include the model name. | ||
operationId: route.method, | ||
// [bajtos] we are omitting consumes and produces, as they are same | ||
// for all methods and they are already specified in top-level fields |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The top-level fields define the defaults while consumes/produces can be overridden at the operation level.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I know. What do you propose? Should we detect whether consumes/produces differs from the default and include it here in such case? I am not sure if strong-remoting actually supports per-method customization of consumes/produces config. Should I just rephrase the comment?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Let's discuss this in #116, so that I can land this PR now and start working on moving the code to loopback-swagger repository.
Added a few minor comments. LGTM! |
I know, that change was landed by #104. While it will be a part of the next release, it's not a part of this pull request.
👍 We should also update the example app, I think @hacksparrow can take care of that, as he is reworking the example app to load loopback-explorer via component-config.json |
[SEMVER-MAJOR] Generate Swagger Spec 2.0 documentation
Notable breaking changes:
at /explorer/swagger.json
are expected to produce an object response with a single property now,
i.e.
{ data: arg }
.In v1.x, we were treating such arg as if "root:true" was specified.
The new behaviour matches the actual implementation in strong-remoting.
operationId
includes model name now, because ids must be uniquehas a way how to specify "use the scheme + host where the doc is served"
X-Forwarded-* headers
The swagger data generated for loopback-example-app passes validation via swagger-api/validator-badge.
Connect to strongloop-internal/scrum-loopback#412
Connect to #54
/to @raymondfeng please review
/cc @STRML @ritch @shelbys