From 220b4d2ea3fc08561ad8b6f833513ac46f6dd144 Mon Sep 17 00:00:00 2001 From: Asai Neko Date: Thu, 29 Jan 2026 10:19:34 +0800 Subject: [PATCH] Optimize swagger Signed-off-by: Asai Neko --- api/auth/exchange.go | 22 +++++++-------- api/auth/magic.go | 22 +++++++-------- api/auth/redirect.go | 30 ++++++++++----------- api/auth/refresh.go | 22 +++++++-------- api/auth/token.go | 22 +++++++-------- api/event/checkin.go | 64 ++++++++++++++++++++++---------------------- api/event/info.go | 24 ++++++++--------- api/user/full.go | 18 ++++++------- api/user/info.go | 22 +++++++-------- api/user/list.go | 24 ++++++++--------- api/user/update.go | 26 +++++++++--------- docs/docs.go | 23 +++++++++++----- docs/swagger.json | 20 +++++++++++++- docs/swagger.yaml | 17 +++++++++++- generate.go | 3 ++- go.mod | 2 +- server/server.go | 5 ++-- 17 files changed, 205 insertions(+), 161 deletions(-) diff --git a/api/auth/exchange.go b/api/auth/exchange.go index c3dc69f..a128108 100644 --- 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 diff --git a/api/auth/magic.go b/api/auth/magic.go index d54a81a..31469c9 100644 --- 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 diff --git a/api/auth/redirect.go b/api/auth/redirect.go index 28cfc8e..aa56dda 100644 --- 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"), diff --git a/api/auth/refresh.go b/api/auth/refresh.go index 850e9f0..8205108 100644 --- 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 diff --git a/api/auth/token.go b/api/auth/token.go index d841766..c8257bb 100644 --- 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 diff --git a/api/event/checkin.go b/api/event/checkin.go index 1eb8767..3c25084 100644 --- 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)) diff --git a/api/event/info.go b/api/event/info.go index 9af5895..232059c 100644 --- 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) diff --git a/api/user/full.go b/api/user/full.go index 35bf3d9..a94b6d7 100644 --- 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, diff --git a/api/user/info.go b/api/user/info.go index faeeac1..70b42e0 100644 --- 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 { diff --git a/api/user/list.go b/api/user/list.go index 9efd91a..bc3dc7b 100644 --- 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"` diff --git a/api/user/update.go b/api/user/update.go index e525c9d..68989f4 100644 --- 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 { diff --git a/docs/docs.go b/docs/docs.go index 13e07b6..b72cea5 100644 --- 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: "{{", diff --git a/docs/swagger.json b/docs/swagger.json index d1426cb..89415d4 100644 --- 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": { diff --git a/docs/swagger.yaml b/docs/swagger.yaml index 72821b7..fe26179 100644 --- 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" diff --git a/generate.go b/generate.go index bae9f07..561b1bd 100644 --- 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 diff --git a/go.mod b/go.mod index e98cf52..3aa5302 100644 --- 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 diff --git a/server/server.go b/server/server.go index 6aa36f8..bbb899f 100644 --- 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