fix: fix Swagger docs by improving comments

99nil · Dec 23, 2023 · 21f3948 · 21f3948
1 parent 9bef969
commit 21f3948
Show file tree

Hide file tree

Showing 9 changed files with 606 additions and 544 deletions.
diff --git a/controllers/account.go b/controllers/account.go
@@ -238,7 +238,7 @@ func (c *ApiController) Signup() {
 // @Param   post_logout_redirect_uri    query    string  false     "post_logout_redirect_uri"
 // @Param   state     query    string  false     "state"
 // @Success 200 {object} controllers.Response The Response object
-// @router /logout [get,post]
+// @router /logout [post]
 func (c *ApiController) Logout() {
 	// https://openid.net/specs/openid-connect-rpinitiated-1_0-final.html
 	accessToken := c.Input().Get("id_token_hint")
@@ -454,6 +454,7 @@ func (c *ApiController) GetUserinfo2() {
 // @Tag Login API
 // @Title GetCaptcha
 // @router /api/get-captcha [get]
+// @Success 200 {object} object.Userinfo The Response object
 func (c *ApiController) GetCaptcha() {
 	applicationId := c.Input().Get("applicationId")
 	isCurrentProvider := c.Input().Get("isCurrentProvider")

diff --git a/controllers/auth.go b/controllers/auth.go
@@ -887,6 +887,7 @@ func (c *ApiController) HandleSamlLogin() {
 // @Tag HandleOfficialAccountEvent API
 // @Title HandleOfficialAccountEvent
 // @router /api/webhook [POST]
+// @Success 200 {object} object.Userinfo The Response object
 func (c *ApiController) HandleOfficialAccountEvent() {
 	respBytes, err := ioutil.ReadAll(c.Ctx.Request.Body)
 	if err != nil {
@@ -917,6 +918,7 @@ func (c *ApiController) HandleOfficialAccountEvent() {
 // @Tag GetWebhookEventType API
 // @Title GetWebhookEventType
 // @router /api/get-webhook-event [GET]
+// @Success 200 {object} object.Userinfo The Response object
 func (c *ApiController) GetWebhookEventType() {
 	lock.Lock()
 	defer lock.Unlock()
@@ -964,6 +966,7 @@ func (c *ApiController) GetCaptchaStatus() {
 // @Tag Callback API
 // @Description Get Login Error Counts
 // @router /api/Callback [post]
+// @Success 200 {object} object.Userinfo The Response object
 func (c *ApiController) Callback() {
 	code := c.GetString("code")
 	state := c.GetString("state")

diff --git a/controllers/enforcer.go b/controllers/enforcer.go
@@ -71,7 +71,7 @@ func (c *ApiController) GetEnforcers() {
 // @Tag Enforcer API
 // @Description get enforcer
 // @Param   id     query    string  true        "The id ( owner/name )  of enforcer"
-// @Success 200 {object} object
+// @Success 200 {object} object.Enforcer
 // @router /get-enforcer [get]
 func (c *ApiController) GetEnforcer() {
 	id := c.Input().Get("id")
@@ -99,7 +99,7 @@ func (c *ApiController) GetEnforcer() {
 // @Description update enforcer
 // @Param   id     query    string  true        "The id ( owner/name )  of enforcer"
 // @Param   enforcer     body    object  true        "The enforcer object"
-// @Success 200 {object} object
+// @Success 200 {object} object.Enforcer
 // @router /update-enforcer [post]
 func (c *ApiController) UpdateEnforcer() {
 	id := c.Input().Get("id")
@@ -120,7 +120,7 @@ func (c *ApiController) UpdateEnforcer() {
 // @Tag Enforcer API
 // @Description add enforcer
 // @Param   enforcer     body    object  true        "The enforcer object"
-// @Success 200 {object} object
+// @Success 200 {object} object.Enforcer
 // @router /add-enforcer [post]
 func (c *ApiController) AddEnforcer() {
 	enforcer := object.Enforcer{}
@@ -139,7 +139,7 @@ func (c *ApiController) AddEnforcer() {
 // @Tag Enforcer API
 // @Description delete enforcer
 // @Param   body    body    object.Enforce  true      "The enforcer object"
-// @Success 200 {object} object
+// @Success 200 {object} object.Enforcer
 // @router /delete-enforcer [post]
 func (c *ApiController) DeleteEnforcer() {
 	var enforcer object.Enforcer

diff --git a/controllers/link.go b/controllers/link.go
@@ -26,8 +26,10 @@ type LinkForm struct {
 }
 
 // Unlink ...
-// @router /unlink [post]
 // @Tag Login API
+// @Title Unlink
+// @router /unlink [post]
+// @Success 200 {object} object.Userinfo The Response object
 func (c *ApiController) Unlink() {
 	user, ok := c.RequireSignedInUser()
 	if !ok {

diff --git a/controllers/user.go b/controllers/user.go
@@ -510,6 +510,7 @@ func (c *ApiController) SetPassword() {
 // @Title CheckUserPassword
 // @router /check-user-password [post]
 // @Tag User API
+// @Success 200 {object} object.Userinfo The Response object
 func (c *ApiController) CheckUserPassword() {
 	var user object.User
 	err := json.Unmarshal(c.Ctx.Input.RequestBody, &user)
@@ -580,6 +581,7 @@ func (c *ApiController) GetUserCount() {
 // @Title AddUserKeys
 // @router /add-user-keys [post]
 // @Tag User API
+// @Success 200 {object} object.Userinfo The Response object
 func (c *ApiController) AddUserKeys() {
 	var user object.User
 	err := json.Unmarshal(c.Ctx.Input.RequestBody, &user)

diff --git a/controllers/verification.go b/controllers/verification.go
@@ -39,6 +39,7 @@ const (
 // @Title SendVerificationCode
 // @Tag Verification API
 // @router /send-verification-code [post]
+// @Success 200 {object} object.Userinfo The Response object
 func (c *ApiController) SendVerificationCode() {
 	var vform form.VerificationForm
 	err := c.ParseForm(&vform)
@@ -229,6 +230,7 @@ func (c *ApiController) SendVerificationCode() {
 // @Title VerifyCaptcha
 // @Tag Verification API
 // @router /verify-captcha [post]
+// @Success 200 {object} object.Userinfo The Response object
 func (c *ApiController) VerifyCaptcha() {
 	var vform form.VerificationForm
 	err := c.ParseForm(&vform)
@@ -271,6 +273,7 @@ func (c *ApiController) VerifyCaptcha() {
 // @Tag Account API
 // @Title ResetEmailOrPhone
 // @router /api/reset-email-or-phone [post]
+// @Success 200 {object} object.Userinfo The Response object
 func (c *ApiController) ResetEmailOrPhone() {
 	user, ok := c.RequireSignedInUser()
 	if !ok {
@@ -365,6 +368,7 @@ func (c *ApiController) ResetEmailOrPhone() {
 // @Tag Verification API
 // @Title VerifyCode
 // @router /api/verify-code [post]
+// @Success 200 {object} object.Userinfo The Response object
 func (c *ApiController) VerifyCode() {
 	var authForm form.AuthForm
 	err := json.Unmarshal(c.Ctx.Input.RequestBody, &authForm)

diff --git a/controllers/webauthn.go b/controllers/webauthn.go
@@ -146,7 +146,7 @@ func (c *ApiController) WebAuthnSigninBegin() {
 }
 
 // WebAuthnSigninFinish
-// @Title WebAuthnSigninBegin
+// @Title WebAuthnSigninFinish
 // @Tag Login API
 // @Description WebAuthn Login Flow 2nd stage
 // @Param   body    body   protocol.CredentialAssertionResponse  true        "authenticator assertion Response"