From 3eeea54a10e73402bb7dd372e6018d226db65309 Mon Sep 17 00:00:00 2001 From: Matt Williams Date: Mon, 21 Nov 2022 07:23:13 -0800 Subject: [PATCH] fix: document the Grants API so that it is right in the openapi.json doc (#3685) * fix: documenting the grants api Signed-off-by: Matt Williams * updated openapi json Signed-off-by: Matt Williams * Update api/grant.go Co-authored-by: Bruce MacDonald * Update api/grant.go Co-authored-by: Bruce MacDonald * Update api/grant.go Co-authored-by: Jeffrey Morgan <251292+jmorganca@users.noreply.github.com> * Update api/grant.go Co-authored-by: Jeffrey Morgan <251292+jmorganca@users.noreply.github.com> * updated openapi3.json after changes Signed-off-by: Matt Williams Signed-off-by: Matt Williams Co-authored-by: Bruce MacDonald Co-authored-by: Jeffrey Morgan <251292+jmorganca@users.noreply.github.com> --- api/grant.go | 34 ++++++++--------- docs/api/openapi3.json | 85 +++++++++++++++++++++++++++++++++--------- 2 files changed, 85 insertions(+), 34 deletions(-) diff --git a/api/grant.go b/api/grant.go index b2454a846e..993d5cd93b 100644 --- a/api/grant.go +++ b/api/grant.go @@ -10,21 +10,21 @@ import ( ) type Grant struct { - ID uid.ID `json:"id"` + ID uid.ID `json:"id" note:"ID of grant created" example:"3w9XyTrkzk"` Created Time `json:"created"` CreatedBy uid.ID `json:"created_by" note:"id of the user that created the grant"` Updated Time `json:"updated"` - User uid.ID `json:"user,omitempty"` - Group uid.ID `json:"group,omitempty"` - Privilege string `json:"privilege" note:"a role or permission"` - Resource string `json:"resource" note:"a resource name in Infra's Universal Resource Notation"` + User uid.ID `json:"user,omitempty" note:"UserID for a user being granted access" example:"6hNnjfjVcc"` + Group uid.ID `json:"group,omitempty" note:"GroupID for a group being granted access" example:"3zMaadcd2U"` + Privilege string `json:"privilege" note:"a role or permission" example:"admin"` + Resource string `json:"resource" note:"a resource name in Infra's Universal Resource Notation" example:"production.namespace"` } type CreateGrantResponse struct { *Grant `json:",inline"` - WasCreated bool `json:"wasCreated"` + WasCreated bool `json:"wasCreated" note:"Indicates that grant was successfully created, false it already existed beforehand" example:"true"` } func (r *CreateGrantResponse) StatusCode() int { @@ -35,13 +35,13 @@ func (r *CreateGrantResponse) StatusCode() int { } type ListGrantsRequest struct { - User uid.ID `form:"user"` - Group uid.ID `form:"group"` - Resource string `form:"resource" example:"production.namespace"` - Destination string `form:"destination" example:"production"` - Privilege string `form:"privilege" example:"view"` - ShowInherited bool `form:"showInherited" note:"if true, this field includes grants that the user inherits through groups"` - ShowSystem bool `form:"showSystem" note:"if true, this shows the connector and other internal grants"` + User uid.ID `form:"user" note:"ID of user granted access" example:"6TjWTAgYYu"` + Group uid.ID `form:"group" note:"ID of group granted access" example:"6k3Eqcqu6B"` + Resource string `form:"resource" example:"production.namespace" note:"a resource name"` + Destination string `form:"destination" example:"production" note:"name of the destination where a connector is installed"` + Privilege string `form:"privilege" example:"view" note:"a role or permission"` + ShowInherited bool `form:"showInherited" note:"if true, this field includes grants that the user inherits through groups" example:"true"` + ShowSystem bool `form:"showSystem" note:"if true, this shows the connector and other internal grants" example:"false"` BlockingRequest PaginationRequest } @@ -144,10 +144,10 @@ func (r ListGrantsRequest) SetPage(page int) Paginatable { // GrantRequest defines a grant request which can be used for creating or deleting grants type GrantRequest struct { - User uid.ID `json:"user"` - Group uid.ID `json:"group"` - UserName string `json:"userName"` - GroupName string `json:"groupName"` + User uid.ID `json:"user" note:"ID of the user granted access" example:"6kdoMDd6PA"` + Group uid.ID `json:"group" note:"ID of the group granted access" example:"6Ti2p7r1h7"` + UserName string `json:"userName" note:"Name of the user granted access" example:"admin@example.com"` + GroupName string `json:"groupName" note:"Name of the group granted access" example:"dev"` Privilege string `json:"privilege" example:"view" note:"a role or permission"` Resource string `json:"resource" example:"production" note:"a resource name in Infra's Universal Resource Notation"` } diff --git a/docs/api/openapi3.json b/docs/api/openapi3.json index 5249b74347..bbc21b4ba6 100644 --- a/docs/api/openapi3.json +++ b/docs/api/openapi3.json @@ -64,23 +64,27 @@ "type": "string" }, "group": { - "example": "4yJ3n3D8E2", + "description": "GroupID for a group being granted access", + "example": "3zMaadcd2U", "format": "uid", "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}", "type": "string" }, "id": { - "example": "4yJ3n3D8E2", + "description": "ID of grant created", + "example": "3w9XyTrkzk", "format": "uid", "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}", "type": "string" }, "privilege": { "description": "a role or permission", + "example": "admin", "type": "string" }, "resource": { "description": "a resource name in Infra's Universal Resource Notation", + "example": "production.namespace", "type": "string" }, "updated": { @@ -90,12 +94,15 @@ "type": "string" }, "user": { - "example": "4yJ3n3D8E2", + "description": "UserID for a user being granted access", + "example": "6hNnjfjVcc", "format": "uid", "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}", "type": "string" }, "wasCreated": { + "description": "Indicates that grant was successfully created, false it already existed beforehand", + "example": "true", "type": "boolean" } } @@ -336,23 +343,27 @@ "type": "string" }, "group": { - "example": "4yJ3n3D8E2", + "description": "GroupID for a group being granted access", + "example": "3zMaadcd2U", "format": "uid", "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}", "type": "string" }, "id": { - "example": "4yJ3n3D8E2", + "description": "ID of grant created", + "example": "3w9XyTrkzk", "format": "uid", "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}", "type": "string" }, "privilege": { "description": "a role or permission", + "example": "admin", "type": "string" }, "resource": { "description": "a resource name in Infra's Universal Resource Notation", + "example": "production.namespace", "type": "string" }, "updated": { @@ -362,7 +373,8 @@ "type": "string" }, "user": { - "example": "4yJ3n3D8E2", + "description": "UserID for a user being granted access", + "example": "6hNnjfjVcc", "format": "uid", "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}", "type": "string" @@ -423,23 +435,27 @@ "type": "string" }, "group": { - "example": "4yJ3n3D8E2", + "description": "GroupID for a group being granted access", + "example": "3zMaadcd2U", "format": "uid", "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}", "type": "string" }, "id": { - "example": "4yJ3n3D8E2", + "description": "ID of grant created", + "example": "3w9XyTrkzk", "format": "uid", "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}", "type": "string" }, "privilege": { "description": "a role or permission", + "example": "admin", "type": "string" }, "resource": { "description": "a resource name in Infra's Universal Resource Notation", + "example": "production.namespace", "type": "string" }, "updated": { @@ -449,7 +465,8 @@ "type": "string" }, "user": { - "example": "4yJ3n3D8E2", + "description": "UserID for a user being granted access", + "example": "6hNnjfjVcc", "format": "uid", "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}", "type": "string" @@ -2810,39 +2827,49 @@ } }, { + "description": "ID of user granted access", + "example": "6TjWTAgYYu", "in": "query", "name": "user", "schema": { - "example": "4yJ3n3D8E2", + "description": "ID of user granted access", + "example": "6TjWTAgYYu", "format": "uid", "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}", "type": "string" } }, { + "description": "ID of group granted access", + "example": "6k3Eqcqu6B", "in": "query", "name": "group", "schema": { - "example": "4yJ3n3D8E2", + "description": "ID of group granted access", + "example": "6k3Eqcqu6B", "format": "uid", "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}", "type": "string" } }, { + "description": "a resource name", "example": "production.namespace", "in": "query", "name": "resource", "schema": { + "description": "a resource name", "example": "production.namespace", "type": "string" } }, { + "description": "name of the destination where a connector is installed", "example": "production", "in": "query", "name": "destination", "schema": { + "description": "name of the destination where a connector is installed", "example": "production", "format": "[a-zA-Z0-9\\-_]", "maxLength": 256, @@ -2851,29 +2878,35 @@ } }, { + "description": "a role or permission", "example": "view", "in": "query", "name": "privilege", "schema": { + "description": "a role or permission", "example": "view", "type": "string" } }, { "description": "if true, this field includes grants that the user inherits through groups", + "example": "true", "in": "query", "name": "showInherited", "schema": { "description": "if true, this field includes grants that the user inherits through groups", + "example": "true", "type": "boolean" } }, { "description": "if true, this shows the connector and other internal grants", + "example": "false", "in": "query", "name": "showSystem", "schema": { "description": "if true, this shows the connector and other internal grants", + "example": "false", "type": "boolean" } }, @@ -3040,12 +3073,15 @@ ], "properties": { "group": { - "example": "4yJ3n3D8E2", + "description": "ID of the group granted access", + "example": "6Ti2p7r1h7", "format": "uid", "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}", "type": "string" }, "groupName": { + "description": "Name of the group granted access", + "example": "dev", "type": "string" }, "privilege": { @@ -3059,12 +3095,15 @@ "type": "string" }, "user": { - "example": "4yJ3n3D8E2", + "description": "ID of the user granted access", + "example": "6kdoMDd6PA", "format": "uid", "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}", "type": "string" }, "userName": { + "description": "Name of the user granted access", + "example": "admin@example.com", "type": "string" } }, @@ -3102,12 +3141,15 @@ ], "properties": { "group": { - "example": "4yJ3n3D8E2", + "description": "ID of the group granted access", + "example": "6Ti2p7r1h7", "format": "uid", "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}", "type": "string" }, "groupName": { + "description": "Name of the group granted access", + "example": "dev", "type": "string" }, "privilege": { @@ -3121,12 +3163,15 @@ "type": "string" }, "user": { - "example": "4yJ3n3D8E2", + "description": "ID of the user granted access", + "example": "6kdoMDd6PA", "format": "uid", "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}", "type": "string" }, "userName": { + "description": "Name of the user granted access", + "example": "admin@example.com", "type": "string" } }, @@ -3266,12 +3311,15 @@ ], "properties": { "group": { - "example": "4yJ3n3D8E2", + "description": "ID of the group granted access", + "example": "6Ti2p7r1h7", "format": "uid", "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}", "type": "string" }, "groupName": { + "description": "Name of the group granted access", + "example": "dev", "type": "string" }, "privilege": { @@ -3285,12 +3333,15 @@ "type": "string" }, "user": { - "example": "4yJ3n3D8E2", + "description": "ID of the user granted access", + "example": "6kdoMDd6PA", "format": "uid", "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}", "type": "string" }, "userName": { + "description": "Name of the user granted access", + "example": "admin@example.com", "type": "string" } },