Optimize swagger

Signed-off-by: Asai Neko <sugar@sne.moe>
2026-01-29 10:19:34 +08:00
parent 3ac1f4165f
commit 220b4d2ea3
17 changed files with 205 additions and 161 deletions
--- a/api/auth/exchange.go
+++ b/api/auth/exchange.go
@@ -10,17 +10,17 @@ import (
 )

 // Exchange handles the authorization code swap process.
-// @Summary      Exchange Auth Code
-// @Description  Exchanges client credentials and user session for a specific redirect authorization code.
-// @Tags         Authentication
-// @Accept       json
-// @Produce      json
-// @Param        payload  body      service_auth.ExchangeData  true  "Exchange Request Credentials"
-// @Success      200      {object}  utils.RespStatus{data=service_auth.ExchangeResponse} "Successful exchange"
-// @Failure      400      {object}  utils.RespStatus{data=nil} "Invalid Input"
-// @Failure      401      {object}  utils.RespStatus{data=nil} "Unauthorized"
-// @Failure      500      {object}  utils.RespStatus{data=nil} "Internal Server Error"
-// @Router       /auth/exchange [post]
+//	@Summary		Exchange Auth Code
+//	@Description	Exchanges client credentials and user session for a specific redirect authorization code.
+//	@Tags			Authentication
+//	@Accept			json
+//	@Produce		json
+//	@Param			payload	body		service_auth.ExchangeData								true	"Exchange Request Credentials"
+//	@Success		200		{object}	utils.RespStatus{data=service_auth.ExchangeResponse}	"Successful exchange"
+//	@Failure		400		{object}	utils.RespStatus{data=nil}								"Invalid Input"
+//	@Failure		401		{object}	utils.RespStatus{data=nil}								"Unauthorized"
+//	@Failure		500		{object}	utils.RespStatus{data=nil}								"Internal Server Error"
+//	@Router			/auth/exchange [post]
 func (self *AuthHandler) Exchange(c *gin.Context) {
 	var exchangeData service_auth.ExchangeData

--- a/api/auth/magic.go
+++ b/api/auth/magic.go
@@ -9,17 +9,17 @@ import (
 )

 // Magic handles the "Magic Link" authentication request.
-// @Summary      Request Magic Link
-// @Description  Verifies Turnstile token and sends an authentication link via email. Returns the URI directly if debug mode is enabled.
-// @Tags         Authentication
-// @Accept       json
-// @Produce      json
-// @Param        payload  body      service_auth.MagicData  true  "Magic Link Request Data"
-// @Success      200      {object}  utils.RespStatus{data=service_auth.MagicResponse} "Successful request"
-// @Failure      400      {object}  utils.RespStatus{data=nil} "Invalid Input"
-// @Failure      403      {object}  utils.RespStatus{data=nil} "Turnstile Verification Failed"
-// @Failure      500      {object}  utils.RespStatus{data=nil} "Internal Server Error"
-// @Router       /auth/magic [post]
+//	@Summary		Request Magic Link
+//	@Description	Verifies Turnstile token and sends an authentication link via email. Returns the URI directly if debug mode is enabled.
+//	@Tags			Authentication
+//	@Accept			json
+//	@Produce		json
+//	@Param			payload	body		service_auth.MagicData								true	"Magic Link Request Data"
+//	@Success		200		{object}	utils.RespStatus{data=service_auth.MagicResponse}	"Successful request"
+//	@Failure		400		{object}	utils.RespStatus{data=nil}							"Invalid Input"
+//	@Failure		403		{object}	utils.RespStatus{data=nil}							"Turnstile Verification Failed"
+//	@Failure		500		{object}	utils.RespStatus{data=nil}							"Internal Server Error"
+//	@Router			/auth/magic [post]
 func (self *AuthHandler) Magic(c *gin.Context) {
 	var magicData service_auth.MagicData

--- a/api/auth/redirect.go
+++ b/api/auth/redirect.go
@@ -9,21 +9,21 @@ import (
 )

 // Redirect handles the post-verification callback and redirects the user to the target application.
-// @Summary      Handle Auth Callback and Redirect
-// @Description  Verifies the temporary email code, ensures the user exists (or creates one), validates the client's redirect URI, and finally performs a 302 redirect with a new authorization code.
-// @Tags         Authentication
-// @Accept       x-www-form-urlencoded
-// @Produce      json
-// @Produce      html
-// @Param        client_id     query     string  true  "Client Identifier"
-// @Param        redirect_uri  query     string  true  "Target Redirect URI"
-// @Param        code          query     string  true  "Temporary Verification Code"
-// @Param        state         query     string  false "Opaque state used to maintain state between the request and callback"
-// @Success      302           {string}  string  "Redirect to the provided RedirectUri with a new code"
-// @Failure      400           {object}  utils.RespStatus{data=nil} "Invalid Input / Client Not Found / URI Mismatch"
-// @Failure      403           {object}  utils.RespStatus{data=nil} "Invalid or Expired Verification Code"
-// @Failure      500           {object}  utils.RespStatus{data=nil} "Internal Server Error"
-// @Router       /auth/redirect [get]
+//	@Summary		Handle Auth Callback and Redirect
+//	@Description	Verifies the temporary email code, ensures the user exists (or creates one), validates the client's redirect URI, and finally performs a 302 redirect with a new authorization code.
+//	@Tags			Authentication
+//	@Accept			x-www-form-urlencoded
+//	@Produce		json
+//	@Produce		html
+//	@Param			client_id		query		string						true	"Client Identifier"
+//	@Param			redirect_uri	query		string						true	"Target Redirect URI"
+//	@Param			code			query		string						true	"Temporary Verification Code"
+//	@Param			state			query		string						false	"Opaque state used to maintain state between the request and callback"
+//	@Success		302				{string}	string						"Redirect to the provided RedirectUri with a new code"
+//	@Failure		400				{object}	utils.RespStatus{data=nil}	"Invalid Input / Client Not Found / URI Mismatch"
+//	@Failure		403				{object}	utils.RespStatus{data=nil}	"Invalid or Expired Verification Code"
+//	@Failure		500				{object}	utils.RespStatus{data=nil}	"Internal Server Error"
+//	@Router			/auth/redirect [get]
 func (self *AuthHandler) Redirect(c *gin.Context) {
 	data := &service_auth.RedirectData{
 		ClientId:    c.Query("client_id"),
--- a/api/auth/refresh.go
+++ b/api/auth/refresh.go
@@ -9,17 +9,17 @@ import (
 )

 // Refresh handles the token rotation process.
-// @Summary      Refresh Access Token
-// @Description  Accepts a valid refresh token to issue a new access token and a rotated refresh token.
-// @Tags         Authentication
-// @Accept       json
-// @Produce      json
-// @Param        payload  body      service_auth.RefreshData  true  "Refresh Token Body"
-// @Success      200      {object}  utils.RespStatus{data=service_auth.TokenResponse} "Successful rotation"
-// @Failure      400      {object}  utils.RespStatus{data=nil} "Invalid Input"
-// @Failure      401      {object}  utils.RespStatus{data=nil} "Invalid Refresh Token"
-// @Failure      500      {object}  utils.RespStatus{data=nil} "Internal Server Error"
-// @Router       /auth/refresh [post]
+//	@Summary		Refresh Access Token
+//	@Description	Accepts a valid refresh token to issue a new access token and a rotated refresh token.
+//	@Tags			Authentication
+//	@Accept			json
+//	@Produce		json
+//	@Param			payload	body		service_auth.RefreshData							true	"Refresh Token Body"
+//	@Success		200		{object}	utils.RespStatus{data=service_auth.TokenResponse}	"Successful rotation"
+//	@Failure		400		{object}	utils.RespStatus{data=nil}							"Invalid Input"
+//	@Failure		401		{object}	utils.RespStatus{data=nil}							"Invalid Refresh Token"
+//	@Failure		500		{object}	utils.RespStatus{data=nil}							"Internal Server Error"
+//	@Router			/auth/refresh [post]
 func (self *AuthHandler) Refresh(c *gin.Context) {
 	var refreshData service_auth.RefreshData

--- a/api/auth/token.go
+++ b/api/auth/token.go
@@ -9,17 +9,17 @@ import (
 )

 // Token exchanges an authorization code for access and refresh tokens.
-// @Summary      Exchange Code for Token
-// @Description  Verifies the provided authorization code and issues a pair of JWT tokens (Access and Refresh).
-// @Tags         Authentication
-// @Accept       json
-// @Produce      json
-// @Param        payload  body      service_auth.TokenData  true  "Token Request Body"
-// @Success      200      {object}  utils.RespStatus{data=service_auth.TokenResponse} "Successful token issuance"
-// @Failure      400      {object}  utils.RespStatus{data=nil} "Invalid Input"
-// @Failure      403      {object}  utils.RespStatus{data=nil} "Invalid or Expired Code"
-// @Failure      500      {object}  utils.RespStatus{data=nil} "Internal Server Error"
-// @Router       /auth/token [post]
+//	@Summary		Exchange Code for Token
+//	@Description	Verifies the provided authorization code and issues a pair of JWT tokens (Access and Refresh).
+//	@Tags			Authentication
+//	@Accept			json
+//	@Produce		json
+//	@Param			payload	body		service_auth.TokenData								true	"Token Request Body"
+//	@Success		200		{object}	utils.RespStatus{data=service_auth.TokenResponse}	"Successful token issuance"
+//	@Failure		400		{object}	utils.RespStatus{data=nil}							"Invalid Input"
+//	@Failure		403		{object}	utils.RespStatus{data=nil}							"Invalid or Expired Code"
+//	@Failure		500		{object}	utils.RespStatus{data=nil}							"Internal Server Error"
+//	@Router			/auth/token [post]
 func (self *AuthHandler) Token(c *gin.Context) {
 	var tokenData service_auth.TokenData