From ff854154669bc73ec964e8d9849520e35d7f8d8f Mon Sep 17 00:00:00 2001 From: Vitor Azevedo Date: Fri, 26 Jul 2024 19:04:11 -0300 Subject: [PATCH 1/2] fix(gin-swagger): Correct routes --- README.md | 2 +- backend/cmd/docs/docs.go | 116 +++++++++++++++++----------------- backend/cmd/docs/swagger.json | 116 +++++++++++++++++----------------- backend/cmd/docs/swagger.yaml | 86 ++++++++++++------------- backend/pkg/http/http.go | 6 +- 5 files changed, 163 insertions(+), 163 deletions(-) diff --git a/README.md b/README.md index 2dc97eb..653d636 100644 --- a/README.md +++ b/README.md @@ -130,7 +130,7 @@ Instale o pacote golang `swag`: Vá para a pasta backend e rode o seguinte comando: ```bash - swag init -g ./cmd/api/main.go -o cmd/docs + path/to/the/go/bin/swag init -g ./cmd/api/main.go -o cmd/docs ``` ![Run and debug tutorial](.github/images/run_and_debug.png) diff --git a/backend/cmd/docs/docs.go b/backend/cmd/docs/docs.go index 026192b..4bebc8c 100644 --- a/backend/cmd/docs/docs.go +++ b/backend/cmd/docs/docs.go @@ -15,118 +15,118 @@ const docTemplate = `{ "host": "{{.Host}}", "basePath": "{{.BasePath}}", "paths": { - "/event-handler": { - "post": { - "description": "Handles event creation, guest addition, email sending, and redirects to Google Meet link.", + "/": { + "get": { + "description": "Renders the form.html page to display user information form.", + "produces": [ + "text/html" + ], + "summary": "Render form page", + "responses": { + "200": { + "description": "HTML content of the form page", + "schema": { + "type": "string" + } + } + } + } + }, + "/callback": { + "get": { + "description": "Exchange code for token and save it", "consumes": [ "application/json" ], "produces": [ "application/json" ], - "summary": "Handle event creation and interaction", + "summary": "Handle OAuth2 callback", "parameters": [ { "type": "string", - "description": "Name of the student", - "name": "name", - "in": "formData", - "required": true - }, - { - "type": "string", - "description": "Email of the student", - "name": "email", - "in": "formData", + "description": "State token", + "name": "state", + "in": "query", "required": true }, { "type": "string", - "description": "Phone number of the student", - "name": "phone", - "in": "formData", + "description": "Authorization code", + "name": "code", + "in": "query", "required": true } ], "responses": { "303": { - "description": "Redirects to Google Meet link", - "schema": { - "type": "string" - } + "description": "Redirects to /" }, "400": { - "description": "No Google Meet link available or other errors", + "description": "State token doesn't match", "schema": { - "$ref": "#/definitions/handlers.ErrorResponse" + "$ref": "#/definitions/http.ErrorResponse" } }, "500": { - "description": "Internal server error", - "schema": { - "$ref": "#/definitions/handlers.ErrorResponse" - } - } - } - } - }, - "/form": { - "get": { - "description": "Renders the form.html page to display user information form.", - "produces": [ - "text/html" - ], - "summary": "Render form page", - "responses": { - "200": { - "description": "HTML content of the form page", + "description": "Unable to retrieve or save token", "schema": { - "type": "string" + "$ref": "#/definitions/http.ErrorResponse" } } } } }, - "/oauth/callback": { - "get": { - "description": "Exchange code for token and save it", + "/event": { + "post": { + "description": "Handles event creation, guest addition, email sending, and redirects to Google Meet link.", "consumes": [ "application/json" ], "produces": [ "application/json" ], - "summary": "Handle OAuth2 callback", + "summary": "Handle event creation and interaction", "parameters": [ { "type": "string", - "description": "State token", - "name": "state", - "in": "query", + "description": "Name of the student", + "name": "name", + "in": "formData", "required": true }, { "type": "string", - "description": "Authorization code", - "name": "code", - "in": "query", + "description": "Email of the student", + "name": "email", + "in": "formData", + "required": true + }, + { + "type": "string", + "description": "Phone number of the student", + "name": "phone", + "in": "formData", "required": true } ], "responses": { "303": { - "description": "Redirects to /" + "description": "Redirects to Google Meet link", + "schema": { + "type": "string" + } }, "400": { - "description": "State token doesn't match", + "description": "No Google Meet link available or other errors", "schema": { - "$ref": "#/definitions/handlers.ErrorResponse" + "$ref": "#/definitions/http.ErrorResponse" } }, "500": { - "description": "Unable to retrieve or save token", + "description": "Internal server error", "schema": { - "$ref": "#/definitions/handlers.ErrorResponse" + "$ref": "#/definitions/http.ErrorResponse" } } } @@ -134,7 +134,7 @@ const docTemplate = `{ } }, "definitions": { - "handlers.ErrorResponse": { + "http.ErrorResponse": { "type": "object", "properties": { "error": { diff --git a/backend/cmd/docs/swagger.json b/backend/cmd/docs/swagger.json index 9fb3a35..abdb18d 100644 --- a/backend/cmd/docs/swagger.json +++ b/backend/cmd/docs/swagger.json @@ -4,118 +4,118 @@ "contact": {} }, "paths": { - "/event-handler": { - "post": { - "description": "Handles event creation, guest addition, email sending, and redirects to Google Meet link.", + "/": { + "get": { + "description": "Renders the form.html page to display user information form.", + "produces": [ + "text/html" + ], + "summary": "Render form page", + "responses": { + "200": { + "description": "HTML content of the form page", + "schema": { + "type": "string" + } + } + } + } + }, + "/callback": { + "get": { + "description": "Exchange code for token and save it", "consumes": [ "application/json" ], "produces": [ "application/json" ], - "summary": "Handle event creation and interaction", + "summary": "Handle OAuth2 callback", "parameters": [ { "type": "string", - "description": "Name of the student", - "name": "name", - "in": "formData", - "required": true - }, - { - "type": "string", - "description": "Email of the student", - "name": "email", - "in": "formData", + "description": "State token", + "name": "state", + "in": "query", "required": true }, { "type": "string", - "description": "Phone number of the student", - "name": "phone", - "in": "formData", + "description": "Authorization code", + "name": "code", + "in": "query", "required": true } ], "responses": { "303": { - "description": "Redirects to Google Meet link", - "schema": { - "type": "string" - } + "description": "Redirects to /" }, "400": { - "description": "No Google Meet link available or other errors", + "description": "State token doesn't match", "schema": { - "$ref": "#/definitions/handlers.ErrorResponse" + "$ref": "#/definitions/http.ErrorResponse" } }, "500": { - "description": "Internal server error", - "schema": { - "$ref": "#/definitions/handlers.ErrorResponse" - } - } - } - } - }, - "/form": { - "get": { - "description": "Renders the form.html page to display user information form.", - "produces": [ - "text/html" - ], - "summary": "Render form page", - "responses": { - "200": { - "description": "HTML content of the form page", + "description": "Unable to retrieve or save token", "schema": { - "type": "string" + "$ref": "#/definitions/http.ErrorResponse" } } } } }, - "/oauth/callback": { - "get": { - "description": "Exchange code for token and save it", + "/event": { + "post": { + "description": "Handles event creation, guest addition, email sending, and redirects to Google Meet link.", "consumes": [ "application/json" ], "produces": [ "application/json" ], - "summary": "Handle OAuth2 callback", + "summary": "Handle event creation and interaction", "parameters": [ { "type": "string", - "description": "State token", - "name": "state", - "in": "query", + "description": "Name of the student", + "name": "name", + "in": "formData", "required": true }, { "type": "string", - "description": "Authorization code", - "name": "code", - "in": "query", + "description": "Email of the student", + "name": "email", + "in": "formData", + "required": true + }, + { + "type": "string", + "description": "Phone number of the student", + "name": "phone", + "in": "formData", "required": true } ], "responses": { "303": { - "description": "Redirects to /" + "description": "Redirects to Google Meet link", + "schema": { + "type": "string" + } }, "400": { - "description": "State token doesn't match", + "description": "No Google Meet link available or other errors", "schema": { - "$ref": "#/definitions/handlers.ErrorResponse" + "$ref": "#/definitions/http.ErrorResponse" } }, "500": { - "description": "Unable to retrieve or save token", + "description": "Internal server error", "schema": { - "$ref": "#/definitions/handlers.ErrorResponse" + "$ref": "#/definitions/http.ErrorResponse" } } } @@ -123,7 +123,7 @@ } }, "definitions": { - "handlers.ErrorResponse": { + "http.ErrorResponse": { "type": "object", "properties": { "error": { diff --git a/backend/cmd/docs/swagger.yaml b/backend/cmd/docs/swagger.yaml index 828c9b3..fbcd8ff 100644 --- a/backend/cmd/docs/swagger.yaml +++ b/backend/cmd/docs/swagger.yaml @@ -1,5 +1,5 @@ definitions: - handlers.ErrorResponse: + http.ErrorResponse: properties: error: type: string @@ -7,45 +7,7 @@ definitions: info: contact: {} paths: - /event-handler: - post: - consumes: - - application/json - description: Handles event creation, guest addition, email sending, and redirects - to Google Meet link. - parameters: - - description: Name of the student - in: formData - name: name - required: true - type: string - - description: Email of the student - in: formData - name: email - required: true - type: string - - description: Phone number of the student - in: formData - name: phone - required: true - type: string - produces: - - application/json - responses: - "303": - description: Redirects to Google Meet link - schema: - type: string - "400": - description: No Google Meet link available or other errors - schema: - $ref: '#/definitions/handlers.ErrorResponse' - "500": - description: Internal server error - schema: - $ref: '#/definitions/handlers.ErrorResponse' - summary: Handle event creation and interaction - /form: + /: get: description: Renders the form.html page to display user information form. produces: @@ -56,7 +18,7 @@ paths: schema: type: string summary: Render form page - /oauth/callback: + /callback: get: consumes: - application/json @@ -80,10 +42,48 @@ paths: "400": description: State token doesn't match schema: - $ref: '#/definitions/handlers.ErrorResponse' + $ref: '#/definitions/http.ErrorResponse' "500": description: Unable to retrieve or save token schema: - $ref: '#/definitions/handlers.ErrorResponse' + $ref: '#/definitions/http.ErrorResponse' summary: Handle OAuth2 callback + /event: + post: + consumes: + - application/json + description: Handles event creation, guest addition, email sending, and redirects + to Google Meet link. + parameters: + - description: Name of the student + in: formData + name: name + required: true + type: string + - description: Email of the student + in: formData + name: email + required: true + type: string + - description: Phone number of the student + in: formData + name: phone + required: true + type: string + produces: + - application/json + responses: + "303": + description: Redirects to Google Meet link + schema: + type: string + "400": + description: No Google Meet link available or other errors + schema: + $ref: '#/definitions/http.ErrorResponse' + "500": + description: Internal server error + schema: + $ref: '#/definitions/http.ErrorResponse' + summary: Handle event creation and interaction swagger: "2.0" diff --git a/backend/pkg/http/http.go b/backend/pkg/http/http.go index 684201e..7a9b669 100644 --- a/backend/pkg/http/http.go +++ b/backend/pkg/http/http.go @@ -42,7 +42,7 @@ func NewApp(config *oauth2.Config, calendar services.CalendarService, email serv // @Description Renders the form.html page to display user information form. // @Produce html // @Success 200 {string} html "HTML content of the form page" -// @Router /form [get] +// @Router / [get] func (app *App) FormHandler(c *gin.Context) { tmpl, err := template.ParseFiles("templates/web/form.html") @@ -66,7 +66,7 @@ func (app *App) FormHandler(c *gin.Context) { // @Success 303 {string} string "Redirects to Google Meet link" // @Failure 400 {object} ErrorResponse "No Google Meet link available or other errors" // @Failure 500 {object} ErrorResponse "Internal server error" -// @Router /event-handler [post] +// @Router /event [post] func (app *App) EventHandler(c *gin.Context) { name := c.PostForm("name") @@ -140,7 +140,7 @@ func (app *App) EventHandler(c *gin.Context) { // @Success 303 "Redirects to /" // @Failure 400 {object} ErrorResponse "State token doesn't match" // @Failure 500 {object} ErrorResponse "Unable to retrieve or save token" -// @Router /oauth/callback [get] +// @Router /callback [get] func (app *App) OAuthCallbackHandler(c *gin.Context) { if c.Query("state") != "state-token" { From b4a43c34f4cc593891138bc3d50052a0520fbb2c Mon Sep 17 00:00:00 2001 From: Vitor Azevedo Date: Fri, 26 Jul 2024 19:20:06 -0300 Subject: [PATCH 2/2] fix(gin-swagger): Add swagger docs app's header --- backend/cmd/api/main.go | 21 +++++++++++++++++++++ backend/cmd/docs/docs.go | 25 +++++++++++++++++++------ backend/cmd/docs/swagger.json | 20 +++++++++++++++++++- backend/cmd/docs/swagger.yaml | 18 +++++++++++++++++- 4 files changed, 76 insertions(+), 8 deletions(-) diff --git a/backend/cmd/api/main.go b/backend/cmd/api/main.go index c33507d..c596e68 100644 --- a/backend/cmd/api/main.go +++ b/backend/cmd/api/main.go @@ -11,6 +11,27 @@ import ( "golang.org/x/oauth2" ) +// @title Faladev API +// @version 1.0 +// @description Esta é uma API exemplo do Faladev, que integra com o Google Calendar e o Gmail. +// @termsOfService http://swagger.io/terms/ + +// @contact.name Suporte da API Faladev +// @contact.url http://www.faladev.com/support +// @contact.email support@faladev.com + +// @license.name Apache 2.0 +// @license.url http://www.apache.org/licenses/LICENSE-2.0.html + +// @host localhost:8080 +// @BasePath / + +// @securityDefinitions.oauth2 OAuth2 +// @securityDefinitions.oauth2.description OAuth2 authorization for accessing the API +// @securityDefinitions.oauth2.flow accessCode + +// @externalDocs.description OpenAPI Specification +// @externalDocs.url https://swagger.io/resources/open-api/ func main() { oauthConfig := config.SetupOAuthConfig() diff --git a/backend/cmd/docs/docs.go b/backend/cmd/docs/docs.go index 4bebc8c..d0fefc7 100644 --- a/backend/cmd/docs/docs.go +++ b/backend/cmd/docs/docs.go @@ -9,7 +9,16 @@ const docTemplate = `{ "info": { "description": "{{escape .Description}}", "title": "{{.Title}}", - "contact": {}, + "termsOfService": "http://swagger.io/terms/", + "contact": { + "name": "Suporte da API Faladev", + "url": "http://www.faladev.com/support", + "email": "support@faladev.com" + }, + "license": { + "name": "Apache 2.0", + "url": "http://www.apache.org/licenses/LICENSE-2.0.html" + }, "version": "{{.Version}}" }, "host": "{{.Host}}", @@ -142,17 +151,21 @@ const docTemplate = `{ } } } + }, + "externalDocs": { + "description": "OpenAPI Specification", + "url": "https://swagger.io/resources/open-api/" } }` // SwaggerInfo holds exported Swagger Info so clients can modify it var SwaggerInfo = &swag.Spec{ - Version: "", - Host: "", - BasePath: "", + Version: "1.0", + Host: "localhost:8080", + BasePath: "/", Schemes: []string{}, - Title: "", - Description: "", + Title: "Faladev API", + Description: "Esta é uma API exemplo do Faladev, que integra com o Google Calendar e o Gmail.", InfoInstanceName: "swagger", SwaggerTemplate: docTemplate, LeftDelim: "{{", diff --git a/backend/cmd/docs/swagger.json b/backend/cmd/docs/swagger.json index abdb18d..f97fb43 100644 --- a/backend/cmd/docs/swagger.json +++ b/backend/cmd/docs/swagger.json @@ -1,8 +1,22 @@ { "swagger": "2.0", "info": { - "contact": {} + "description": "Esta é uma API exemplo do Faladev, que integra com o Google Calendar e o Gmail.", + "title": "Faladev API", + "termsOfService": "http://swagger.io/terms/", + "contact": { + "name": "Suporte da API Faladev", + "url": "http://www.faladev.com/support", + "email": "support@faladev.com" + }, + "license": { + "name": "Apache 2.0", + "url": "http://www.apache.org/licenses/LICENSE-2.0.html" + }, + "version": "1.0" }, + "host": "localhost:8080", + "basePath": "/", "paths": { "/": { "get": { @@ -131,5 +145,9 @@ } } } + }, + "externalDocs": { + "description": "OpenAPI Specification", + "url": "https://swagger.io/resources/open-api/" } } \ No newline at end of file diff --git a/backend/cmd/docs/swagger.yaml b/backend/cmd/docs/swagger.yaml index fbcd8ff..3482890 100644 --- a/backend/cmd/docs/swagger.yaml +++ b/backend/cmd/docs/swagger.yaml @@ -1,11 +1,27 @@ +basePath: / definitions: http.ErrorResponse: properties: error: type: string type: object +externalDocs: + description: OpenAPI Specification + url: https://swagger.io/resources/open-api/ +host: localhost:8080 info: - contact: {} + contact: + email: support@faladev.com + name: Suporte da API Faladev + url: http://www.faladev.com/support + description: Esta é uma API exemplo do Faladev, que integra com o Google Calendar + e o Gmail. + license: + name: Apache 2.0 + url: http://www.apache.org/licenses/LICENSE-2.0.html + termsOfService: http://swagger.io/terms/ + title: Faladev API + version: "1.0" paths: /: get: