feat: update swagger api json with tags (#347)

Signed-off-by: Товарищ программист <2962928213@qq.com>
casdoor · Dec 3, 2021 · 07fa438 · 07fa438
1 parent d2565e0
commit 07fa438
Show file tree

Hide file tree

Showing 19 changed files with 675 additions and 112 deletions.
diff --git a/controllers/account.go b/controllers/account.go
@@ -71,6 +71,7 @@ type HumanCheck struct {
 }
 
 // Signup
+// @Tag Login API
 // @Title Signup
 // @Description sign up a new user
 // @Param   username     formData    string  true        "The username to sign up"
@@ -177,6 +178,7 @@ func (c *ApiController) Signup() {
 
 // Logout
 // @Title Logout
+// @Tag Login API
 // @Description logout the current user
 // @Success 200 {object} controllers.Response The Response object
 // @router /logout [post]
@@ -192,6 +194,7 @@ func (c *ApiController) Logout() {
 
 // GetAccount
 // @Title GetAccount
+// @Tag Account API
 // @Description get the details of the current account
 // @Success 200 {object} controllers.Response The Response object
 // @router /get-account [get]
@@ -213,6 +216,9 @@ func (c *ApiController) GetAccount() {
 }
 
 // GetHumanCheck ...
+// @Tag Login API
+// @Title GetHumancheck
+// @router /api/get-human-check [get]
 func (c *ApiController) GetHumanCheck() {
 	c.Data["json"] = HumanCheck{Type: "none"}
 

diff --git a/controllers/application.go b/controllers/application.go
@@ -24,6 +24,7 @@ import (
 
 // GetApplications
 // @Title GetApplications
+// @Tag Application API
 // @Description get all applications
 // @Param   owner     query    string  true        "The owner of applications."
 // @Success 200 {array} object.Application The Response object
@@ -45,6 +46,7 @@ func (c *ApiController) GetApplications() {
 
 // GetApplication
 // @Title GetApplication
+// @Tag Application API
 // @Description get the detail of an application
 // @Param   id     query    string  true        "The id of the application."
 // @Success 200 {object} object.Application The Response object
@@ -58,6 +60,7 @@ func (c *ApiController) GetApplication() {
 
 // GetUserApplication
 // @Title GetUserApplication
+// @Tag Application API
 // @Description get the detail of the user's application
 // @Param   id     query    string  true        "The id of the user"
 // @Success 200 {object} object.Application The Response object
@@ -76,6 +79,7 @@ func (c *ApiController) GetUserApplication() {
 
 // UpdateApplication
 // @Title UpdateApplication
+// @Tag Application API
 // @Description update an application
 // @Param   id     query    string  true        "The id of the application"
 // @Param   body    body   object.Application  true        "The details of the application"
@@ -96,6 +100,7 @@ func (c *ApiController) UpdateApplication() {
 
 // AddApplication
 // @Title AddApplication
+// @Tag Application API
 // @Description add an application
 // @Param   body    body   object.Application  true        "The details of the application"
 // @Success 200 {object} controllers.Response The Response object
@@ -113,6 +118,7 @@ func (c *ApiController) AddApplication() {
 
 // DeleteApplication
 // @Title DeleteApplication
+// @Tag Application API
 // @Description delete an application
 // @Param   body    body   object.Application  true        "The details of the application"
 // @Success 200 {object} controllers.Response The Response object

diff --git a/controllers/auth.go b/controllers/auth.go
@@ -75,6 +75,7 @@ func (c *ApiController) HandleLoggedIn(application *object.Application, user *ob
 
 // GetApplicationLogin ...
 // @Title GetApplicationLogin
+// @Tag Login API
 // @Description get application login
 // @Param   clientId    query    string  true        "client id"
 // @Param   responseType    query    string  true        "response type"
@@ -108,6 +109,7 @@ func setHttpClient(idProvider idp.IdProvider, providerType string) {
 
 // Login ...
 // @Title Login
+// @Tag Login API
 // @Description login
 // @Param   oAuthParams     query    string  true        "oAuth parameters"
 // @Param   body    body   RequestForm  true        "Login information"

diff --git a/controllers/base.go b/controllers/base.go
@@ -21,10 +21,16 @@ import (
 	"github.com/casbin/casdoor/util"
 )
 
+// controller for handlers under /api uri
 type ApiController struct {
 	beego.Controller
 }
 
+// controller for handlers directly under / (root)
+type RootController struct {
+	ApiController
+}
+
 type SessionData struct {
 	ExpireTime int64
 }

diff --git a/controllers/ldap.go b/controllers/ldap.go
@@ -16,6 +16,7 @@ package controllers
 
 import (
 	"encoding/json"
+
 	"github.com/casbin/casdoor/object"
 	"github.com/casbin/casdoor/util"
 )
@@ -43,6 +44,9 @@ type LdapSyncResp struct {
 	Failed []object.LdapRespUser `json:"failed"`
 }
 
+// @Tag Account API
+// @Title GetLdapser
+// @router /get-ldap-user [post]
 func (c *ApiController) GetLdapUser() {
 	ldapServer := LdapServer{}
 	err := json.Unmarshal(c.Ctx.Input.RequestBody, &ldapServer)
@@ -96,13 +100,19 @@ func (c *ApiController) GetLdapUser() {
 	c.ServeJSON()
 }
 
+// @Tag Account API
+// @Title GetLdaps
+// @router /get-ldaps [post]
 func (c *ApiController) GetLdaps() {
 	owner := c.Input().Get("owner")
 
 	c.Data["json"] = Response{Status: "ok", Data: object.GetLdaps(owner)}
 	c.ServeJSON()
 }
 
+// @Tag Account API
+// @Title GetLdap
+// @router /get-ldap [post]
 func (c *ApiController) GetLdap() {
 	id := c.Input().Get("id")
 
@@ -115,6 +125,9 @@ func (c *ApiController) GetLdap() {
 	c.ServeJSON()
 }
 
+// @Tag Account API
+// @Title AddLdap
+// @router /add-ldap [post]
 func (c *ApiController) AddLdap() {
 	var ldap object.Ldap
 	err := json.Unmarshal(c.Ctx.Input.RequestBody, &ldap)
@@ -143,6 +156,9 @@ func (c *ApiController) AddLdap() {
 	c.ServeJSON()
 }
 
+// @Tag Account API
+// @Title UpdateLdap
+// @router /update-ldap [post]
 func (c *ApiController) UpdateLdap() {
 	var ldap object.Ldap
 	err := json.Unmarshal(c.Ctx.Input.RequestBody, &ldap)
@@ -161,6 +177,9 @@ func (c *ApiController) UpdateLdap() {
 	c.ServeJSON()
 }
 
+// @Tag Account API
+// @Title DeleteLdap
+// @router /delete-ldap [post]
 func (c *ApiController) DeleteLdap() {
 	var ldap object.Ldap
 	err := json.Unmarshal(c.Ctx.Input.RequestBody, &ldap)
@@ -172,6 +191,9 @@ func (c *ApiController) DeleteLdap() {
 	c.ServeJSON()
 }
 
+// @Tag Account API
+// @Title SyncLdapUsers
+// @router /sync-ldap-users [post]
 func (c *ApiController) SyncLdapUsers() {
 	owner := c.Input().Get("owner")
 	ldapId := c.Input().Get("ldapId")
@@ -191,6 +213,9 @@ func (c *ApiController) SyncLdapUsers() {
 	c.ServeJSON()
 }
 
+// @Tag Account API
+// @Title CheckLdapUserExist
+// @router /check-ldap-users-exist [post]
 func (c *ApiController) CheckLdapUsersExist() {
 	owner := c.Input().Get("owner")
 	var uuids []string

diff --git a/controllers/link.go b/controllers/link.go
@@ -25,6 +25,8 @@ type LinkForm struct {
 }
 
 // Unlink ...
+// @router /unlink [post]
+// @Tag Login API
 func (c *ApiController) Unlink() {
 	userId, ok := c.RequireSignedIn()
 	if !ok {

diff --git a/controllers/oidc_discovery.go b/controllers/oidc_discovery.go
@@ -16,12 +16,18 @@ package controllers
 
 import "github.com/casbin/casdoor/object"
 
-func (c *ApiController) GetOidcDiscovery() {
+// @Title GetOidcDiscovery
+// @Tag OIDC API
+// @router /.well-known/openid-configuration [get]
+func (c *RootController) GetOidcDiscovery() {
 	c.Data["json"] = object.GetOidcDiscovery()
 	c.ServeJSON()
 }
 
-func (c *ApiController) GetOidcCert() {
+// @Title GetOidcCert
+// @Tag OIDC API
+// @router /api/certs [get]
+func (c *RootController) GetOidcCert() {
 	jwks, err := object.GetJSONWebKeySet()
 	if err != nil {
 		c.ResponseError(err.Error())

diff --git a/controllers/organization.go b/controllers/organization.go
@@ -24,6 +24,7 @@ import (
 
 // GetOrganizations ...
 // @Title GetOrganizations
+// @Tag Organization API
 // @Description get organizations
 // @Param   owner     query    string  true        "owner"
 // @Success 200 {array} object.Organization The Response object
@@ -45,6 +46,7 @@ func (c *ApiController) GetOrganizations() {
 
 // GetOrganization ...
 // @Title GetOrganization
+// @Tag Organization API
 // @Description get organization
 // @Param   id     query    string  true        "organization id"
 // @Success 200 {object} object.Organization The Response object
@@ -58,6 +60,7 @@ func (c *ApiController) GetOrganization() {
 
 // UpdateOrganization ...
 // @Title UpdateOrganization
+// @Tag Organization API
 // @Description update organization
 // @Param   id     query    string  true        "The id of the organization"
 // @Param   body    body   object.Organization  true        "The details of the organization"
@@ -78,6 +81,7 @@ func (c *ApiController) UpdateOrganization() {
 
 // AddOrganization ...
 // @Title AddOrganization
+// @Tag Organization API
 // @Description add organization
 // @Param   body    body   object.Organization  true        "The details of the organization"
 // @Success 200 {object} controllers.Response The Response object
@@ -95,6 +99,7 @@ func (c *ApiController) AddOrganization() {
 
 // DeleteOrganization ...
 // @Title DeleteOrganization
+// @Tag Organization API
 // @Description delete organization
 // @Param   body    body   object.Organization  true        "The details of the organization"
 // @Success 200 {object} controllers.Response The Response object

diff --git a/controllers/provider.go b/controllers/provider.go
@@ -24,6 +24,7 @@ import (
 
 // GetProviders
 // @Title GetProviders
+// @Tag Provider API
 // @Description get providers
 // @Param   owner     query    string  true        "The owner of providers"
 // @Success 200 {array} object.Provider The Response object
@@ -44,6 +45,7 @@ func (c *ApiController) GetProviders() {
 }
 
 // @Title GetProvider
+// @Tag Provider API
 // @Description get provider
 // @Param   id    query    string  true        "The id of the provider"
 // @Success 200 {object} object.Provider The Response object
@@ -56,6 +58,7 @@ func (c *ApiController) GetProvider() {
 }
 
 // @Title UpdateProvider
+// @Tag Provider API
 // @Description update provider
 // @Param   id    query    string  true        "The id of the provider"
 // @Param   body    body   object.Provider  true        "The details of the provider"
@@ -75,6 +78,7 @@ func (c *ApiController) UpdateProvider() {
 }
 
 // @Title AddProvider
+// @Tag Provider API
 // @Description add provider
 // @Param   body    body   object.Provider  true        "The details of the provider"
 // @Success 200 {object} controllers.Response The Response object
@@ -91,6 +95,7 @@ func (c *ApiController) AddProvider() {
 }
 
 // @Title DeleteProvider
+// @Tag Provider API
 // @Description delete provider
 // @Param   body    body   object.Provider  true        "The details of the provider"
 // @Success 200 {object} controllers.Response The Response object

diff --git a/controllers/record.go b/controllers/record.go
@@ -22,6 +22,7 @@ import (
 
 // GetRecords
 // @Title GetRecords
+// @Tag Record API
 // @Description get all records
 // @Param   pageSize     query    string  true        "The size of each page"
 // @Param   p     query    string  true        "The number of the page"
@@ -42,6 +43,7 @@ func (c *ApiController) GetRecords() {
 }
 
 // GetRecordsByFilter
+// @Tag Record API
 // @Title GetRecordsByFilter
 // @Description get records by filter
 // @Param   body    body   object.Records  true  "filter Record message"

diff --git a/controllers/resource.go b/controllers/resource.go
@@ -27,6 +27,9 @@ import (
 	"github.com/casbin/casdoor/util"
 )
 
+// @router /get-resources [get]
+// @Tag Resource API
+// @Title GetResources
 func (c *ApiController) GetResources() {
 	owner := c.Input().Get("owner")
 	user := c.Input().Get("user")
@@ -43,13 +46,19 @@ func (c *ApiController) GetResources() {
 	}
 }
 
+// @Tag Resource API
+// @Title GetResource
+// @router /get-resource [get]
 func (c *ApiController) GetResource() {
 	id := c.Input().Get("id")
 
 	c.Data["json"] = object.GetResource(id)
 	c.ServeJSON()
 }
 
+// @Tag Resource API
+// @Title UpdateResource
+// @router /update-resource [post]
 func (c *ApiController) UpdateResource() {
 	id := c.Input().Get("id")
 
@@ -63,6 +72,9 @@ func (c *ApiController) UpdateResource() {
 	c.ServeJSON()
 }
 
+// @Tag Resource API
+// @Title AddResource
+// @router /add-resource [post]
 func (c *ApiController) AddResource() {
 	var resource object.Resource
 	err := json.Unmarshal(c.Ctx.Input.RequestBody, &resource)
@@ -74,6 +86,9 @@ func (c *ApiController) AddResource() {
 	c.ServeJSON()
 }
 
+// @Tag Resource API
+// @Title DeleteResource
+// @router /delete-resource [post]
 func (c *ApiController) DeleteResource() {
 	var resource object.Resource
 	err := json.Unmarshal(c.Ctx.Input.RequestBody, &resource)
@@ -96,6 +111,9 @@ func (c *ApiController) DeleteResource() {
 	c.ServeJSON()
 }
 
+// @Tag Resource API
+// @Title UploadResource
+// @router /upload-resource [post]
 func (c *ApiController) UploadResource() {
 	owner := c.Input().Get("owner")
 	username := c.Input().Get("user")