docs: API workspace agents and builds #5538
Conversation
mtojek
changed the title
| DisconnectedAt *time.Time `json:"disconnected_at,omitempty"` | ||
| Status WorkspaceAgentStatus `json:"status"` | ||
| ID uuid.UUID `json:"id" format:"uuid"` | ||
| CreatedAt time.Time `json:"created_at" format:"date-time"` |
There was a problem hiding this comment.
Perhaps I've asked before, but is there a way to automatically transform these based on the Go type? It seems unfortunate we'd have to tag every new struct, and we will almost certainly miss to add the tag to fields in the future.
It'd be nice if format was reserved as an override since uuid and time.Time are essentially never a different format (would take a custom json Marshaller at which point using format would be appropriate).
There was a problem hiding this comment.
I'm afraid that we would need a fork to apply this feature, let's say, auto-format. It doesn't look like something we can truly solve just with validation.
I'm not sure why it hasn't been implemented this way. Even official examples suggest using format tags.
There was a problem hiding this comment.
I can certainly understand why it's not the default (due to middlewares and handlers that can do whatever). But it'd be nice to enable such a feature.
Do you think they'd be open to it if we made a PR? Seems like many people could benefit.
There was a problem hiding this comment.
At the moment, we're using version swaggo v1.8.6, but I can try to bump it to v1.8.9 so that we will also benefit from future PRs. AFAIR v1.8.9 added a lot of noise around all possible values of time.Duration or strange value examples:
- "value": 0
+ "value": -9223372036854776000There was a problem hiding this comment.
Ah, if v1.8.9 is problematic we can punt it for now unless you think there's a benefit to upgrading?
There was a problem hiding this comment.
Let me prepare a draft PR and we can discuss the upgrade there.
| @@ -65,13 +65,15 @@ type WorkspaceBuild struct { | |||
| InitiatorID uuid.UUID `json:"initiator_id" format:"uuid"` | |||
| InitiatorUsername string `json:"initiator_name"` | |||
| Job ProvisionerJob `json:"job"` | |||
| Reason BuildReason `db:"reason" json:"reason"` | |||
| Reason BuildReason `db:"reason" json:"reason" enums:"initiator,autostart,autostop"` | |||
There was a problem hiding this comment.
Nice work! Once we get the docs in shape, it'd be nice to try to process the Go code to find these enums automatically.
Btw, would it be possible to move this enum description to the type? Like:
// BuildReason ...
// @enum initiator,autostart,autostop
type BuildReason stringPerhaps not supported by swaggo.
There was a problem hiding this comment.
There are some magic undocumented extensions like x-enum-varnames or x-enum-descriptions, but I don't think that this is what we're looking for.
See swaggo/swag#984
There was a problem hiding this comment.
Indeed, that seems useful with enums that are number based and have string representations in (de-)serialization.
| DisconnectedAt *time.Time `json:"disconnected_at,omitempty"` | ||
| Status WorkspaceAgentStatus `json:"status"` | ||
| ID uuid.UUID `json:"id" format:"uuid"` | ||
| CreatedAt time.Time `json:"created_at" format:"date-time"` |
There was a problem hiding this comment.
Ah, if v1.8.9 is problematic we can punt it for now unless you think there's a benefit to upgrading?
Related: #3522
Blocker: #5506 (this PR is built on top of that branch)Changes:
workspaceagents.goworkspacebuilds.go(also affects/workspaces)