From fdbcb21950e798974175efa151f89473591293df Mon Sep 17 00:00:00 2001 From: Tony Tam Date: Fri, 8 Apr 2016 07:44:51 -0700 Subject: [PATCH] added notes for additional issues --- versions/3.0.md | 128 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) diff --git a/versions/3.0.md b/versions/3.0.md index 1d6a2d02a9..294ed3a2fe 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -1,5 +1,133 @@ # OpenAPI Specification +### DO NOT MERGE + +These are comments for discussion and should be turned into separate PRs + +#### NOTES + +## Both HTTP and HTTPS ports cannot be specified #214 + +Proposal: We have schemes, host (+ port), basePath, all which are typically linked to gether. Suggest we produce a new object: + +```yaml +hosts: + - scheme: http + host: foo.com + port: 8080 + basePath: /bar + - scheme: https + host: foo.com + port: 8443 + basePath: /baz +``` + +And remove the separate `host`, `basePath`, `schemes`. Because the port will never be the same between http, https, it makes no sense to support multiple ones + +Fixes #489, #214 + + +## Why don't host and basePath support path templating? #169 + +- [ ] Proposal: this belongs under parent #574 + +## Support an operation to have multiple specifications per path (e.g. multiple POST operation per path) #182 + +- [ ] Proposal: this is a payload issue, move to parent #586 + +## Allow for overloading/aliasing of route path #213 + +- [ ] Proposal: change in #70 would address this + +## Allow references between operations inside descriptions. #239 + +- [ ] Proposal: this is really about _links_ and belongs in the #586 issue + +## Swagger.next: Let's not use hashes anymore #208 + +- [ ] Proposal: while true, moving to arrays causes more problems than it solves. Suggest we close this with no change. + +## Group multiple parameter definitions for better maintainability #445 + +- [ ] Proposal: close. Using global parameters will help with this, and references to arrays of parameters is just wrong.a + + +## Allow documenting HATEOAS APIs (pathless operations) #577 + +- [ ] Proposal: do not support pathless operations. It's against the spirit of the specification as being declarative. The support for links _inside_ a path though, will be covered by #574 and #586. Remove reference to #560 and link to others. + +## Message format 'wrappers' #555 + +- [ ] Proposal: Move discussion to parent issue #586, this is really about a payload definition, which is covered by that meta issue. Non-structural. + +## Adding optional SLA definitions with the Spec #541 + +- [ ] proposal: Add an optional SLA to the specification, follow the same locations / hierarchy as consumes/produces. Need a SME to take this on and propose a structure. + +## No provision to group API's and then $ref it to reference it in other file #508 + +- [ ] Proposal: I believe what this issue is about is to essentially include an entire path definition into a `path`. This isn't possible currently because PIOs are in a hash, and you can not have a $ref in it. Here is a proposed solution: + +```yaml +paths: + /pet: + get: + ... + /health: + $ref: '#/x-paths/health' + '#/x-paths': {} + +# note the location `x-paths` is just illustrative, it could be anywhere allowed by the schema +x-paths: + /store: + get: + ... + /users: + get: + ... +``` + +treat any fragment or file reference as a "merge" against the root paths object. It resolves like this: + +```yaml +paths: + /pet: + get: + ... + /health: + $ref: '#/x-paths/health' + /store: + get: + ... + /users: + get: + ... +``` + +## Clarify when consumes/produces take effect #581 + +- [ ] Proposal: document it, following the HTTP specification for when content-type and accepts headers are acceptable + +## Resource types / patterns for Path Item Objects #588 + +- [ ] Proposal: Ignore it. I don't think we want implicit operations (get|put|post|delete) on a path, consider for 3.1 + +## Allow implicit path parameter matching #132 + +- [ ] Proposal: close. This would be addressed by proposal for #341 + +## Support for multiple request/response models based on headers #146 + +- [ ] Proposal: this is a payload issue, move to parent #586 + +## Global/common parameters #341 + +- [ ] Proposal: Add parameters at the root of the schema. Incompatible parameters will be ignored. Duplicate parameters will use the lower level (i.e. operation) parameter definition. There is no "ignore" parameter mechanism. + + +#### END NOTES + + #### Version 3.0 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](http://www.ietf.org/rfc/rfc2119.txt).