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

--- a/api/event/checkin.go
+++ b/api/event/checkin.go
@@ -10,17 +10,17 @@ import (
 )

 // Checkin generates a check-in code for a specific event.
-// @Summary      Generate Check-in Code
-// @Description  Creates a temporary check-in code for the authenticated user and event.
-// @Tags         Event
-// @Accept       json
-// @Produce      json
-// @Param        event_id  query     string  true  "Event UUID"
-// @Success      200       {object}  utils.RespStatus{data=service_event.CheckinResponse} "Successfully generated code"
-// @Failure      400       {object}  utils.RespStatus{data=nil} "Invalid Input"
-// @Failure      500       {object}  utils.RespStatus{data=nil} "Internal Server Error"
-// @Security     ApiKeyAuth
-// @Router       /event/checkin [get]
+//	@Summary		Generate Check-in Code
+//	@Description	Creates a temporary check-in code for the authenticated user and event.
+//	@Tags			Event
+//	@Accept			json
+//	@Produce		json
+//	@Param			event_id	query		string													true	"Event UUID"
+//	@Success		200			{object}	utils.RespStatus{data=service_event.CheckinResponse}	"Successfully generated code"
+//	@Failure		400			{object}	utils.RespStatus{data=nil}								"Invalid Input"
+//	@Failure		500			{object}	utils.RespStatus{data=nil}								"Internal Server Error"
+//	@Security		ApiKeyAuth
+//	@Router			/event/checkin [get]
 func (self *EventHandler) Checkin(c *gin.Context) {
 	userIdOrig, _ := c.Get("user_id")
 	userId, _ := uuid.Parse(userIdOrig.(string))
@@ -49,16 +49,16 @@ func (self *EventHandler) Checkin(c *gin.Context) {
 }

 // CheckinSubmit validates a check-in code to complete attendance.
-// @Summary      Submit Check-in Code
-// @Description  Submits the generated code to mark the user as attended.
-// @Tags         Event
-// @Accept       json
-// @Produce      json
-// @Param        payload  body      service_event.CheckinSubmitData  true  "Checkin Code Data"
-// @Success      200      {object}  utils.RespStatus{data=nil} "Attendance marked successfully"
-// @Failure      400      {object}  utils.RespStatus{data=nil} "Invalid Code or Input"
-// @Security     ApiKeyAuth
-// @Router       /event/checkin/submit [post]
+//	@Summary		Submit Check-in Code
+//	@Description	Submits the generated code to mark the user as attended.
+//	@Tags			Event
+//	@Accept			json
+//	@Produce		json
+//	@Param			payload	body		service_event.CheckinSubmitData	true	"Checkin Code Data"
+//	@Success		200		{object}	utils.RespStatus{data=nil}		"Attendance marked successfully"
+//	@Failure		400		{object}	utils.RespStatus{data=nil}		"Invalid Code or Input"
+//	@Security		ApiKeyAuth
+//	@Router			/event/checkin/submit [post]
 func (self *EventHandler) CheckinSubmit(c *gin.Context) {
 	var data service_event.CheckinSubmitData
 	if err := c.ShouldBindJSON(&data); err != nil {
@@ -82,17 +82,17 @@ func (self *EventHandler) CheckinSubmit(c *gin.Context) {
 }

 // CheckinQuery retrieves the check-in status of a user for an event.
-// @Summary      Query Check-in Status
-// @Description  Returns the timestamp of when the user checked in, or null if not yet checked in.
-// @Tags         Event
-// @Accept       json
-// @Produce      json
-// @Param        event_id  query     string  true  "Event UUID"
-// @Success      200       {object}  utils.RespStatus{data=service_event.CheckinQueryResponse} "Current attendance status"
-// @Failure      400       {object}  utils.RespStatus{data=nil} "Invalid Input"
-// @Failure      404       {object}  utils.RespStatus{data=nil} "Record Not Found"
-// @Security     ApiKeyAuth
-// @Router       /event/checkin/query [get]
+//	@Summary		Query Check-in Status
+//	@Description	Returns the timestamp of when the user checked in, or null if not yet checked in.
+//	@Tags			Event
+//	@Accept			json
+//	@Produce		json
+//	@Param			event_id	query		string														true	"Event UUID"
+//	@Success		200			{object}	utils.RespStatus{data=service_event.CheckinQueryResponse}	"Current attendance status"
+//	@Failure		400			{object}	utils.RespStatus{data=nil}									"Invalid Input"
+//	@Failure		404			{object}	utils.RespStatus{data=nil}									"Record Not Found"
+//	@Security		ApiKeyAuth
+//	@Router			/event/checkin/query [get]
 func (self *EventHandler) CheckinQuery(c *gin.Context) {
 	userIdOrig, _ := c.Get("user_id")
 	userId, _ := uuid.Parse(userIdOrig.(string))
--- a/api/event/info.go
+++ b/api/event/info.go
@@ -10,18 +10,18 @@ import (
 )

 // Info retrieves basic information about a specific event.
-// @Summary      Get Event Information
-// @Description  Fetches the name, start time, and end time of an event using its UUID.
-// @Tags         Event
-// @Accept       json
-// @Produce      json
-// @Param        event_id  query     string  true  "Event UUID"
-// @Success      200       {object}  utils.RespStatus{data=service_event.InfoResponse} "Successful retrieval"
-// @Failure      400       {object}  utils.RespStatus{data=nil} "Invalid Input"
-// @Failure      404       {object}  utils.RespStatus{data=nil} "Event Not Found"
-// @Failure      500       {object}  utils.RespStatus{data=nil} "Internal Server Error"
-// @Security     ApiKeyAuth
-// @Router       /event/info [get]
+//	@Summary		Get Event Information
+//	@Description	Fetches the name, start time, and end time of an event using its UUID.
+//	@Tags			Event
+//	@Accept			json
+//	@Produce		json
+//	@Param			event_id	query		string												true	"Event UUID"
+//	@Success		200			{object}	utils.RespStatus{data=service_event.InfoResponse}	"Successful retrieval"
+//	@Failure		400			{object}	utils.RespStatus{data=nil}							"Invalid Input"
+//	@Failure		404			{object}	utils.RespStatus{data=nil}							"Event Not Found"
+//	@Failure		500			{object}	utils.RespStatus{data=nil}							"Internal Server Error"
+//	@Security		ApiKeyAuth
+//	@Router			/event/info [get]
 func (self *EventHandler) Info(c *gin.Context) {
 	eventIdOrig := c.Query("event_id")
 	eventId, err := uuid.Parse(eventIdOrig)
--- a/api/user/full.go
+++ b/api/user/full.go
@@ -9,15 +9,15 @@ import (
 )

 // Full retrieves the complete list of users directly from the database table.
-// @Summary      Get Full User Table
-// @Description  Fetches all user records without pagination. This is typically used for administrative overview or data export.
-// @Tags         User
-// @Accept       json
-// @Produce      json
-// @Success      200      {object}  utils.RespStatus{data=service_user.UserTableResponse} "Successful retrieval of full user table"
-// @Failure      500      {object}  utils.RespStatus{data=nil} "Internal Server Error (Database Error)"
-// @Security     ApiKeyAuth
-// @Router       /user/full [get]
+//	@Summary		Get Full User Table
+//	@Description	Fetches all user records without pagination. This is typically used for administrative overview or data export.
+//	@Tags			User
+//	@Accept			json
+//	@Produce		json
+//	@Success		200	{object}	utils.RespStatus{data=service_user.UserTableResponse}	"Successful retrieval of full user table"
+//	@Failure		500	{object}	utils.RespStatus{data=nil}								"Internal Server Error (Database Error)"
+//	@Security		ApiKeyAuth
+//	@Router			/user/full [get]
 func (self *UserHandler) Full(c *gin.Context) {
 	userTablePayload := &service_user.UserTablePayload{
 		Context: c,
--- a/api/user/info.go
+++ b/api/user/info.go
@@ -10,17 +10,17 @@ import (
 )

 // Info retrieves the profile information of the currently authenticated user.
-// @Summary      Get My User Information
-// @Description  Fetches the complete profile data for the user associated with the provided session/token.
-// @Tags         User
-// @Accept       json
-// @Produce      json
-// @Success      200      {object}  utils.RespStatus{data=service_user.UserInfoData} "Successful profile retrieval"
-// @Failure      403      {object}  utils.RespStatus{data=nil} "Missing User ID / Unauthorized"
-// @Failure      404      {object}  utils.RespStatus{data=nil} "User Not Found"
-// @Failure      500      {object}  utils.RespStatus{data=nil} "Internal Server Error (UUID Parse Failed)"
-// @Security     ApiKeyAuth
-// @Router       /user/info [get]
+//	@Summary		Get My User Information
+//	@Description	Fetches the complete profile data for the user associated with the provided session/token.
+//	@Tags			User
+//	@Accept			json
+//	@Produce		json
+//	@Success		200	{object}	utils.RespStatus{data=service_user.UserInfoData}	"Successful profile retrieval"
+//	@Failure		403	{object}	utils.RespStatus{data=nil}							"Missing User ID / Unauthorized"
+//	@Failure		404	{object}	utils.RespStatus{data=nil}							"User Not Found"
+//	@Failure		500	{object}	utils.RespStatus{data=nil}							"Internal Server Error (UUID Parse Failed)"
+//	@Security		ApiKeyAuth
+//	@Router			/user/info [get]
 func (self *UserHandler) Info(c *gin.Context) {
 	userIdOrig, ok := c.Get("user_id")
 	if !ok {
--- a/api/user/list.go
+++ b/api/user/list.go
@@ -9,18 +9,18 @@ import (
 )

 // List retrieves a paginated list of users from the search engine.
-// @Summary      List Users
-// @Description  Fetches a list of users with support for pagination via limit and offset. Data is sourced from the search engine for high performance.
-// @Tags         User
-// @Accept       json
-// @Produce      json
-// @Param        limit   query     string  false  "Maximum number of users to return (default 0)"
-// @Param        offset  query     string  true   "Number of users to skip"
-// @Success      200     {object}  utils.RespStatus{data=[]data.UserSearchDoc} "Successful paginated list retrieval"
-// @Failure      400     {object}  utils.RespStatus{data=nil} "Invalid Input (Format Error)"
-// @Failure      500     {object}  utils.RespStatus{data=nil} "Internal Server Error (Search Engine or Missing Offset)"
-// @Security     ApiKeyAuth
-// @Router       /user/list [get]
+//	@Summary		List Users
+//	@Description	Fetches a list of users with support for pagination via limit and offset. Data is sourced from the search engine for high performance.
+//	@Tags			User
+//	@Accept			json
+//	@Produce		json
+//	@Param			limit	query		string										false	"Maximum number of users to return (default 0)"
+//	@Param			offset	query		string										true	"Number of users to skip"
+//	@Success		200		{object}	utils.RespStatus{data=[]data.UserSearchDoc}	"Successful paginated list retrieval"
+//	@Failure		400		{object}	utils.RespStatus{data=nil}					"Invalid Input (Format Error)"
+//	@Failure		500		{object}	utils.RespStatus{data=nil}					"Internal Server Error (Search Engine or Missing Offset)"
+//	@Security		ApiKeyAuth
+//	@Router			/user/list [get]
 func (self *UserHandler) List(c *gin.Context) {
 	type ListQuery struct {
 		Limit  *string `form:"limit"`
--- a/api/user/update.go
+++ b/api/user/update.go
@@ -10,19 +10,19 @@ import (
 )

 // Update modifies the profile information for the currently authenticated user.
-// @Summary      Update User Information
-// @Description  Updates specific profile fields such as username, nickname, subtitle, avatar (URL), and bio (Base64).
-// @Description  Validation: Username (5-255 chars), Nickname (max 24 chars), Subtitle (max 32 chars).
-// @Tags         User
-// @Accept       json
-// @Produce      json
-// @Param        payload  body      service_user.UserInfoData  true  "Updated User Profile Data"
-// @Success      200      {object}  utils.RespStatus{data=nil} "Successful profile update"
-// @Failure      400      {object}  utils.RespStatus{data=nil} "Invalid Input (Validation Failed)"
-// @Failure      403      {object}  utils.RespStatus{data=nil} "Missing User ID / Unauthorized"
-// @Failure      500      {object}  utils.RespStatus{data=nil} "Internal Server Error (Database Error / UUID Parse Failed)"
-// @Security     ApiKeyAuth
-// @Router       /user/update [patch]
+//	@Summary		Update User Information
+//	@Description	Updates specific profile fields such as username, nickname, subtitle, avatar (URL), and bio (Base64).
+//	@Description	Validation: Username (5-255 chars), Nickname (max 24 chars), Subtitle (max 32 chars).
+//	@Tags			User
+//	@Accept			json
+//	@Produce		json
+//	@Param			payload	body		service_user.UserInfoData	true	"Updated User Profile Data"
+//	@Success		200		{object}	utils.RespStatus{data=nil}	"Successful profile update"
+//	@Failure		400		{object}	utils.RespStatus{data=nil}	"Invalid Input (Validation Failed)"
+//	@Failure		403		{object}	utils.RespStatus{data=nil}	"Missing User ID / Unauthorized"
+//	@Failure		500		{object}	utils.RespStatus{data=nil}	"Internal Server Error (Database Error / UUID Parse Failed)"
+//	@Security		ApiKeyAuth
+//	@Router			/user/update [patch]
 func (self *UserHandler) Update(c *gin.Context) {
 	userIdOrig, ok := c.Get("user_id")
 	if !ok {
--- a/docs/docs.go
+++ b/docs/docs.go
@@ -9,7 +9,16 @@ const docTemplate = `{
    "info": {
        "description": "{{escape .Description}}",
        "title": "{{.Title}}",
-        "contact": {},
+        "termsOfService": "http://swagger.io/terms/",
+        "contact": {
+            "name": "API Support",
+            "url": "http://www.swagger.io/support",
+            "email": "support@swagger.io"
+        },
+        "license": {
+            "name": "Apache 2.0",
+            "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
+        },
        "version": "{{.Version}}"
    },
    "host": "{{.Host}}",
@@ -1462,12 +1471,12 @@ const docTemplate = `{

 // SwaggerInfo holds exported Swagger Info so clients can modify it
 var SwaggerInfo = &swag.Spec{
-	Version:          "",
-	Host:             "",
-	BasePath:         "",
-	Schemes:          []string{},
-	Title:            "",
-	Description:      "",
+	Version:          "1.0",
+	Host:             "localhost:8000",
+	BasePath:         "/api/v1",
+	Schemes:          []string{"http", "https"},
+	Title:            "NixCN CMS API",
+	Description:      "API Docs based on Gin framework",
 	InfoInstanceName: "swagger",
 	SwaggerTemplate:  docTemplate,
 	LeftDelim:        "{{",
--- a/docs/swagger.json
+++ b/docs/swagger.json
@@ -1,8 +1,26 @@
 {
+    "schemes": [
+        "http",
+        "https"
+    ],
    "swagger": "2.0",
    "info": {
-        "contact": {}
+        "description": "API Docs based on Gin framework",
+        "title": "NixCN CMS API",
+        "termsOfService": "http://swagger.io/terms/",
+        "contact": {
+            "name": "API Support",
+            "url": "http://www.swagger.io/support",
+            "email": "support@swagger.io"
+        },
+        "license": {
+            "name": "Apache 2.0",
+            "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
+        },
+        "version": "1.0"
    },
+    "host": "localhost:8000",
+    "basePath": "/api/v1",
    "paths": {
        "/auth/exchange": {
            "post": {
--- a/docs/swagger.yaml
+++ b/docs/swagger.yaml
@@ -1,3 +1,4 @@
+basePath: /api/v1
 definitions:
  data.User:
    properties:
@@ -154,8 +155,19 @@ definitions:
      status:
        type: string
    type: object
+host: localhost:8000
 info:
-  contact: {}
+  contact:
+    email: support@swagger.io
+    name: API Support
+    url: http://www.swagger.io/support
+  description: API Docs based on Gin framework
+  license:
+    name: Apache 2.0
+    url: http://www.apache.org/licenses/LICENSE-2.0.html
+  termsOfService: http://swagger.io/terms/
+  title: NixCN CMS API
+  version: "1.0"
 paths:
  /auth/exchange:
    post:
@@ -823,4 +835,7 @@ paths:
      summary: Update User Information
      tags:
      - User
+schemes:
+- http
+- https
 swagger: "2.0"
--- a/generate.go
+++ b/generate.go
@@ -2,4 +2,5 @@ package main

 //go:generate go run ./cmd/gen_exception/main.go

-//go:generate swag init
+//go:generate swag fmt
+//go:generate swag init -g server/server.go
--- a/go.mod
+++ b/go.mod
@@ -19,7 +19,6 @@ require (
 	github.com/spf13/viper v1.21.0
 	github.com/swaggo/files v1.0.1
 	github.com/swaggo/gin-swagger v1.6.1
-	github.com/swaggo/swag v1.16.6
 	go.opentelemetry.io/contrib/bridges/otelslog v0.14.0
 	go.opentelemetry.io/contrib/instrumentation/github.com/gin-gonic/gin/otelgin v0.64.0
 	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.49.0
@@ -113,6 +112,7 @@ require (
 	github.com/spf13/cast v1.10.0 // indirect
 	github.com/spf13/pflag v1.0.10 // indirect
 	github.com/subosito/gotenv v1.6.0 // indirect
+	github.com/swaggo/swag v1.16.6 // indirect
 	github.com/tjfoc/gmsm v1.4.1 // indirect
 	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
 	github.com/ugorji/go/codec v1.3.1 // indirect
--- a/server/server.go
+++ b/server/server.go
@@ -27,7 +27,7 @@ import (
 // @contact.email  support@swagger.io
 // @license.name  Apache 2.0
 // @license.url   http://www.apache.org/licenses/LICENSE-2.0.html
-// @host      localhost:8080
+// @host      localhost:8000
 // @BasePath  /api/v1
 // @schemes   http https
 func Start(ctx context.Context) {
@@ -39,10 +39,11 @@ func Start(ctx context.Context) {
 	r := gin.New()
 	r.Use(otelgin.Middleware(viper.GetString("server.service_name")))
 	r.Use(middleware.GinLogger())
-	r.Use(gin.Recovery())

 	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

+	r.Use(gin.Recovery())
+
 	api.Handler(r.Group("/api/v1"))

 	// Start http server