[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.
The top-level fields define the defaults while consumes/produces can be overridden at the operation level.
There was a problem hiding this comment.
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.
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.
operationIdincludes 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