feat: add go backend API docs

Signed-off-by: Kininaru <shiftregister233@outlook.com>

controllers/account.go

@@ -58,7 +58,7 @@ type Response struct {
 // @Description register a new user
 // @Param   username     formData    string  true        "The username to register"
 // @Param   password     formData    string  true        "The password"
-// @Success 200 {object} controllers.api_controller.Response The Response object
+// @Success 200 {object} controllers.Response The Response object
 // @router /register [post]
 func (c *ApiController) Register() {
 	var resp Response
@@ -104,7 +104,7 @@ func (c *ApiController) Register() {
 
 // @Title Logout
 // @Description logout the current user
-// @Success 200 {object} controllers.api_controller.Response The Response object
+// @Success 200 {object} controllers.Response The Response object
 // @router /logout [post]
 func (c *ApiController) Logout() {
 	var resp Response
@@ -120,6 +120,10 @@ func (c *ApiController) Logout() {
 	c.ServeJSON()
 }
 
+// @Title GetAccount
+// @Description get the details of the current account
+// @Success 200 {object} controllers.Response The Response object
+// @router /get-account [get]
 func (c *ApiController) GetAccount() {
 	var resp Response
 
@@ -138,6 +142,12 @@ func (c *ApiController) GetAccount() {
 	c.ServeJSON()
 }
 
+// @Title UploadAvatar
+// @Description register a new user
+// @Param   avatarfile   formData    string  true        "The base64 encode of avatarfile"
+// @Param   password     formData    string  true        "The password"
+// @Success 200 {object} controllers.Response The Response object
+// @router /upload-avatar [post]
 func (c *ApiController) UploadAvatar() {
 	var resp Response
 	username := c.GetSessionUser()

controllers/application.go

@@ -20,6 +20,11 @@ import (
 	"github.com/casdoor/casdoor/object"
 )
 
+// @Title GetApplications
+// @Description get all applications
+// @Param   owner     query    string  true        "The owner of applications."
+// @Success 200 {array} object.Application The Response object
+// @router /get-applications [get]
 func (c *ApiController) GetApplications() {
 	owner := c.Input().Get("owner")
 
@@ -27,6 +32,11 @@ func (c *ApiController) GetApplications() {
 	c.ServeJSON()
 }
 
+// @Title GetApplication
+// @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
+// @router /get-application [get]
 func (c *ApiController) GetApplication() {
 	id := c.Input().Get("id")
 
@@ -34,6 +44,12 @@ func (c *ApiController) GetApplication() {
 	c.ServeJSON()
 }
 
+// @Title UpdateApplication
+// @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"
+// @Success 200 {object} controllers.Response The Response object
+// @router /update-application [post]
 func (c *ApiController) UpdateApplication() {
 	id := c.Input().Get("id")
 
@@ -47,6 +63,11 @@ func (c *ApiController) UpdateApplication() {
 	c.ServeJSON()
 }
 
+// @Title AddApplication
+// @Description add an application
+// @Param   body    body   object.Application  true        "The details of the application"
+// @Success 200 {object} controllers.Response The Response object
+// @router /add-application [post]
 func (c *ApiController) AddApplication() {
 	var application object.Application
 	err := json.Unmarshal(c.Ctx.Input.RequestBody, &application)
@@ -58,6 +79,11 @@ func (c *ApiController) AddApplication() {
 	c.ServeJSON()
 }
 
+// @Title DeleteApplication
+// @Description delete an application
+// @Param   body    body   object.Application  true        "The details of the application"
+// @Success 200 {object} controllers.Response The Response object
+// @router /delete-application [post]
 func (c *ApiController) DeleteApplication() {
 	var application object.Application
 	err := json.Unmarshal(c.Ctx.Input.RequestBody, &application)

controllers/auth.go

@@ -53,6 +53,15 @@ func (c *ApiController) HandleLoggedIn(userId string, form *RequestForm) *Respon
 	return resp
 }
 
+// @Title GetApplicationLogin
+// @Description get application login
+// @Param   clientId    query    string  true        "client id"
+// @Param   responseType    query    string  true        "response type"
+// @Param   redirectUri    query    string  true        "redirect uri"
+// @Param   scope    query    string  true        "scope"
+// @Param   state    query    string  true        "state"
+// @Success 200 {object} controllers.api_controller.Response The Response object
+// @router /update-application [get]
 func (c *ApiController) GetApplicationLogin() {
 	var resp Response
 
@@ -72,6 +81,12 @@ func (c *ApiController) GetApplicationLogin() {
 	c.ServeJSON()
 }
 
+// @Title Login
+// @Description login
+// @Param   oAuthParams     query    string  true        "oAuth parameters"
+// @Param   body    body   RequestForm  true        "Login information"
+// @Success 200 {object} controllers.api_controller.Response The Response object
+// @router /login [post]
 func (c *ApiController) Login() {
 	resp := &Response{Status: "null", Msg: ""}
 	var form RequestForm

controllers/organization.go

@@ -20,6 +20,11 @@ import (
 	"github.com/casdoor/casdoor/object"
 )
 
+// @Title GetOrganizations
+// @Description get organizations
+// @Param   owner     query    string  true        "owner"
+// @Success 200 {array} object.Organization The Response object
+// @router /get-organizations [get]
 func (c *ApiController) GetOrganizations() {
 	owner := c.Input().Get("owner")
 
@@ -27,6 +32,11 @@ func (c *ApiController) GetOrganizations() {
 	c.ServeJSON()
 }
 
+// @Title GetOrganization
+// @Description get organization
+// @Param   id     query    string  true        "organization id"
+// @Success 200 {object} object.Organization The Response object
+// @router /get-organization [get]
 func (c *ApiController) GetOrganization() {
 	id := c.Input().Get("id")
 
@@ -34,6 +44,12 @@ func (c *ApiController) GetOrganization() {
 	c.ServeJSON()
 }
 
+// @Title UpdateOrganization
+// @Description update organization
+// @Param   id     query    string  true        "The id of the organization"
+// @Param   body    body   object.Organization  true        "The details of the organization"
+// @Success 200 {object} controllers.Response The Response object
+// @router /update-organization [post]
 func (c *ApiController) UpdateOrganization() {
 	id := c.Input().Get("id")
 
@@ -47,6 +63,11 @@ func (c *ApiController) UpdateOrganization() {
 	c.ServeJSON()
 }
 
+// @Title AddOrganization
+// @Description add organization
+// @Param   body    body   object.Organization  true        "The details of the organization"
+// @Success 200 {object} controllers.Response The Response object
+// @router /add-organization [post]
 func (c *ApiController) AddOrganization() {
 	var organization object.Organization
 	err := json.Unmarshal(c.Ctx.Input.RequestBody, &organization)
@@ -58,6 +79,11 @@ func (c *ApiController) AddOrganization() {
 	c.ServeJSON()
 }
 
+// @Title DeleteOrganization
+// @Description delete organization
+// @Param   body    body   object.Organization  true        "The details of the organization"
+// @Success 200 {object} controllers.Response The Response object
+// @router /delete-organization [post]
 func (c *ApiController) DeleteOrganization() {
 	var organization object.Organization
 	err := json.Unmarshal(c.Ctx.Input.RequestBody, &organization)

controllers/provider.go

@@ -20,6 +20,11 @@ import (
 	"github.com/casdoor/casdoor/object"
 )
 
+// @Title GetProviders
+// @Description get providers
+// @Param   owner     query    string  true        "The owner of providers"
+// @Success 200 {array} object.Provider The Response object
+// @router /get-providers [get]
 func (c *ApiController) GetProviders() {
 	owner := c.Input().Get("owner")
 
@@ -27,6 +32,11 @@ func (c *ApiController) GetProviders() {
 	c.ServeJSON()
 }
 
+// @Title GetProvider
+// @Description get provider
+// @Param   id    query    string  true        "The id of the provider"
+// @Success 200 {object} object.Provider The Response object
+// @router /get-provider [get]
 func (c *ApiController) GetProvider() {
 	id := c.Input().Get("id")
 
@@ -34,6 +44,12 @@ func (c *ApiController) GetProvider() {
 	c.ServeJSON()
 }
 
+// @Title UpdateProvider
+// @Description update provider
+// @Param   id    query    string  true        "The id of the provider"
+// @Param   body    body   object.Provider  true        "The details of the provider"
+// @Success 200 {object} controllers.Response The Response object
+// @router /update-provider [post]
 func (c *ApiController) UpdateProvider() {
 	id := c.Input().Get("id")
 
@@ -47,6 +63,11 @@ func (c *ApiController) UpdateProvider() {
 	c.ServeJSON()
 }
 
+// @Title AddProvider
+// @Description add provider
+// @Param   body    body   object.Provider  true        "The details of the provider"
+// @Success 200 {object} controllers.Response The Response object
+// @router /add-provider [post]
 func (c *ApiController) AddProvider() {
 	var provider object.Provider
 	err := json.Unmarshal(c.Ctx.Input.RequestBody, &provider)
@@ -58,6 +79,11 @@ func (c *ApiController) AddProvider() {
 	c.ServeJSON()
 }
 
+// @Title DeleteProvider
+// @Description delete provider
+// @Param   body    body   object.Provider  true        "The details of the provider"
+// @Success 200 {object} controllers.Response The Response object
+// @router /delete-provider [post]
 func (c *ApiController) DeleteProvider() {
 	var provider object.Provider
 	err := json.Unmarshal(c.Ctx.Input.RequestBody, &provider)

controllers/token.go

@@ -20,6 +20,11 @@ import (
 	"github.com/casdoor/casdoor/object"
 )
 
+// @Title GetTokens
+// @Description get tokens
+// @Param   owner     query    string  true        "The owner of tokens"
+// @Success 200 {array} object.Token The Response object
+// @router /get-tokens [get]
 func (c *ApiController) GetTokens() {
 	owner := c.Input().Get("owner")
 
@@ -27,6 +32,11 @@ func (c *ApiController) GetTokens() {
 	c.ServeJSON()
 }
 
+// @Title GetToken
+// @Description get token
+// @Param   id     query    string  true        "The id of token"
+// @Success 200 {object} object.Token The Response object
+// @router /get-token [get]
 func (c *ApiController) GetToken() {
 	id := c.Input().Get("id")
 
@@ -34,6 +44,12 @@ func (c *ApiController) GetToken() {
 	c.ServeJSON()
 }
 
+// @Title UpdateToken
+// @Description update token
+// @Param   id     query    string  true        "The id of token"
+// @Param   body    body   object.Token  true        "Details of the token"
+// @Success 200 {object} controllers.Response The Response object
+// @router /update-token [post]
 func (c *ApiController) UpdateToken() {
 	id := c.Input().Get("id")
 
@@ -47,6 +63,11 @@ func (c *ApiController) UpdateToken() {
 	c.ServeJSON()
 }
 
+// @Title AddToken
+// @Description add token
+// @Param   body    body   object.Token  true        "Details of the token"
+// @Success 200 {object} controllers.Response The Response object
+// @router /add-token [post]
 func (c *ApiController) AddToken() {
 	var token object.Token
 	err := json.Unmarshal(c.Ctx.Input.RequestBody, &token)
@@ -58,6 +79,11 @@ func (c *ApiController) AddToken() {
 	c.ServeJSON()
 }
 
+// @Title DeleteToken
+// @Description delete token
+// @Param   body    body   object.Token  true        "Details of the token"
+// @Success 200 {object} controllers.Response The Response object
+// @router /delete-token [post]
 func (c *ApiController) DeleteToken() {
 	var token object.Token
 	err := json.Unmarshal(c.Ctx.Input.RequestBody, &token)
@@ -69,6 +95,14 @@ func (c *ApiController) DeleteToken() {
 	c.ServeJSON()
 }
 
+// @Title GetOAuthToken
+// @Description get oAuth token
+// @Param   grant_type     query    string  true        "oAuth grant type"
+// @Param   client_id     query    string  true        "oAuth client id"
+// @Param   client_secret     query    string  true        "oAuth client secret"
+// @Param   code     query    string  true        "oAuth code"
+// @Success 200 {object} object.TokenWrapper The Response object
+// @router /login/oauth/access_token [post]
 func (c *ApiController) GetOAuthToken() {
 	grantType := c.Input().Get("grant_type")
 	clientId := c.Input().Get("client_id")

controllers/user.go

@@ -20,11 +20,20 @@ import (
 	"github.com/casdoor/casdoor/object"
 )
 
+// @Title GetGlobalUsers
+// @Description get global users
+// @Success 200 {array} object.User The Response object
+// @router /get-global-users [get]
 func (c *ApiController) GetGlobalUsers() {
 	c.Data["json"] = object.GetGlobalUsers()
 	c.ServeJSON()
 }
 
+// @Title GetUsers
+// @Description
+// @Param   owner     query    string  true        "The owner of users"
+// @Success 200 {array} object.User The Response object
+// @router /get-users [get]
 func (c *ApiController) GetUsers() {
 	owner := c.Input().Get("owner")
 
@@ -32,6 +41,11 @@ func (c *ApiController) GetUsers() {
 	c.ServeJSON()
 }
 
+// @Title GetUser
+// @Description get user
+// @Param   id     query    string  true        "The id of the user"
+// @Success 200 {object} object.User The Response object
+// @router /get-user [get]
 func (c *ApiController) GetUser() {
 	id := c.Input().Get("id")
 
@@ -39,6 +53,12 @@ func (c *ApiController) GetUser() {
 	c.ServeJSON()
 }
 
+// @Title UpdateUser
+// @Description update user
+// @Param   id     query    string  true        "The id of the user"
+// @Param   body    body   object.User  true        "The details of the user"
+// @Success 200 {object} controllers.Response The Response object
+// @router /update-user [post]
 func (c *ApiController) UpdateUser() {
 	id := c.Input().Get("id")
 
@@ -52,6 +72,11 @@ func (c *ApiController) UpdateUser() {
 	c.ServeJSON()
 }
 
+// @Title AddUser
+// @Description add user
+// @Param   body    body   object.User  true        "The details of the user"
+// @Success 200 {object} controllers.Response The Response object
+// @router /add-user [post]
 func (c *ApiController) AddUser() {
 	var user object.User
 	err := json.Unmarshal(c.Ctx.Input.RequestBody, &user)
@@ -63,6 +88,11 @@ func (c *ApiController) AddUser() {
 	c.ServeJSON()
 }
 
+// @Title DeleteUser
+// @Description delete user
+// @Param   body    body   object.User  true        "The details of the user"
+// @Success 200 {object} controllers.Response The Response object
+// @router /delete-user [post]
 func (c *ApiController) DeleteUser() {
 	var user object.User
 	err := json.Unmarshal(c.Ctx.Input.RequestBody, &user)