Skip to content

Commit

Permalink
fix: document the Grants API so that it is right in the openapi.json …
Browse files Browse the repository at this point in the history 
…doc (#3685)

* fix: documenting the grants api

Signed-off-by: Matt Williams <[email protected]>

* updated openapi json

Signed-off-by: Matt Williams <[email protected]>

* Update api/grant.go

Co-authored-by: Bruce MacDonald <[email protected]>

* Update api/grant.go

Co-authored-by: Bruce MacDonald <[email protected]>

* Update api/grant.go

Co-authored-by: Jeffrey Morgan <[email protected]>

* Update api/grant.go

Co-authored-by: Jeffrey Morgan <[email protected]>

* updated openapi3.json after changes

Signed-off-by: Matt Williams <[email protected]>

Signed-off-by: Matt Williams <[email protected]>
Co-authored-by: Bruce MacDonald <[email protected]>
Co-authored-by: Jeffrey Morgan <[email protected]>
  • Loading branch information
@technovangelist @BruceMacD @jmorganca
3 people authored Nov 21, 2022
1 parent de02338 commit 3eeea54
Show file tree
Hide file tree
Showing 2 changed files with 85 additions and 34 deletions.
34 changes: 17 additions & 17 deletions api/grant.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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
}
Expand Down Expand Up @@ -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:"[email protected]"`
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"`
}
Expand Down
85 changes: 68 additions & 17 deletions docs/api/openapi3.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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": {
Expand All @@ -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"
}
}
Expand Down Expand Up @@ -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": {
Expand All @@ -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"
Expand Down Expand Up @@ -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": {
Expand All @@ -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"
Expand Down Expand Up @@ -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,
Expand All @@ -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"
}
},
Expand Down Expand Up @@ -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": {
Expand All @@ -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": "[email protected]",
"type": "string"
}
},
Expand Down Expand Up @@ -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": {
Expand All @@ -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": "[email protected]",
"type": "string"
}
},
Expand Down Expand Up @@ -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": {
Expand All @@ -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": "[email protected]",
"type": "string"
}
},
Expand Down

0 comments on commit 3eeea54

Please sign in to comment.