[skip ci] Define an OpenAPI document for vic-machine#6132
Conversation
zjs
force-pushed
the
feature/vic-machine-service-spec
branch
from
53f695e to
074099c
Compare
lib/apiservers/service/swagger.json
Outdated
| "security": [] | ||
| } | ||
| }, | ||
| "/{target}": { |
There was a problem hiding this comment.
Should this be /targets/{target}? This would reduce the chances of target name colliding with other resource names under /.
There was a problem hiding this comment.
Because {target} must be a valid IP address or hostname, I think the risk of collision is low.
Given the current vic-machine operations, and general model that all VIC operations involve a vSphere resource of some sort, /version may be the only resource directly under /.
There was a problem hiding this comment.
Name collisions aside, it just seems odd to address a target under /. We're not managing the target after all. As a consumer of the API, I would expect endpoints under / to be directly relevant to the vic-machine service itself, like /version.
| "/{target}/datacenter/{datacenter}": { | ||
| "get": { | ||
| "summary": "Show information about the specified vSphere resources", | ||
| "description": "Making a `GET` request on a datacenter will return information about the state of the host firewall on those resources.", |
There was a problem hiding this comment.
The path of the resource /{target}/datacenter/ does not indicate it has anything to do with firewalls. Can we change that reflect what the call is actually about?
There was a problem hiding this comment.
I expect that the resource will include additional information; firewall status is just the first item.
We could expose separate resources for each piece of information (/{target}/datacenter/{datacenter}/firewall, /{target}/datacenter/{datacenter}/foo, /{target}/datacenter/{datacenter}/bar), but instead I think it makes sense to have a single /{target}/datacenter/{datacenter} endpoint with a response body like below, and add sub-resources on an as-needed basis if necessary:
{
"firewall": {
},
"foo": {
},
"bar": {
}
}There was a problem hiding this comment.
Yes, this is fine if more than just firewall info is going to be retrieved.
Insert "/target" into path. See: vmware#6132 (comment)
Insert "/target" into path. See: vmware#6132 (comment)
| // Make sure not to overwrite this file after you generated it because all your edits would be lost! | ||
|
|
||
| func main() { | ||
|
|
There was a problem hiding this comment.
This file was generated by the swagger tool.
Given that the file was generated, and go fmt didn't remove it, I'm inclined to leave it as-is.
If I start touching the file, I'm going to wonder if I should also remove line 55, wonder why there's no line between 32 and 33, but is a line between 50 and 52, and... none of that seems like a good use of time.
Insert "/target" into path. See: vmware#6132 (comment)
zjs
force-pushed
the
feature/vic-machine-service-spec
branch
from
4e0f2a8 to
ce3db37
Compare
Insert "/target" into path. See: vmware#6132 (comment)
zjs
force-pushed
the
feature/vic-machine-service-spec
branch
from
ce3db37 to
b17246d
Compare
Insert "/target" into path. See: vmware#6132 (comment)
zjs
force-pushed
the
feature/vic-machine-service-spec
branch
from
b17246d to
a9e20a3
Compare
Insert "/target" into path See: vmware#6132 (comment)
Use an OpenAPI (Swagger) document to define a preliminary API for vic-machine based on the vic-machine API design document (vmware#6116). This document is expected to evolve as implementation proceeds.
zjs
force-pushed
the
feature/vic-machine-service-spec
branch
from
a9e20a3 to
7def8c1
Compare
5 participants
Use an OpenAPI (Swagger) document to define a preliminary API for
vic-machine based on the vic-machine API design document (#6116).
This document is expected to evolve as implementation proceeds.
Resolves #6015.
Note: this change builds on #6124 and, once approved, I would like this to land as the second commit on
feature/vic-machine-service.