Skip to content

Commit

Permalink
feat: swagger using swaggo/swag and gin-swagger
Browse files Browse the repository at this point in the history 
Signed-off-by: Ales Verbic <[email protected]>
  • Loading branch information
@verbotenj
verbotenj committed Oct 18, 2023
1 parent 15c1da9 commit 3710a4f
Show file tree
Hide file tree
Showing 8 changed files with 582 additions and 15 deletions.
7 changes: 7 additions & 0 deletions Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,13 @@ mod-tidy:
clean:
rm -f $(BINARIES)

format: mod-tidy
go fmt ./...

swagger:
swag f -g api.go -d api,output
swag i -g api.go -d api,output

test: mod-tidy
go test -v ./...

Expand Down
18 changes: 16 additions & 2 deletions api/api.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,10 @@ import (
"sync"
"time"

_ "github.com/blinklabs-io/snek/docs"
"github.com/gin-gonic/gin"
swaggerFiles "github.com/swaggo/files" // swagger embed files
ginSwagger "github.com/swaggo/gin-swagger" // gin-swagger middleware
)

type API interface {
Expand Down Expand Up @@ -71,6 +74,18 @@ func (a *APIv1) Engine() *gin.Engine {
return a.engine
}

// @title Snek API
// @version v1
// @description Snek API
// @Schemes http
// @BasePath /v1

// @contact.name Blink Labs
// @contact.url https://blinklabs.io
// @contact.email [email protected]

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
func (a *APIv1) Start() error {
address := a.host + ":" + a.port
// Use buffered channel to not block goroutine
Expand Down Expand Up @@ -140,8 +155,7 @@ func ConfigureRouter(debug bool) *gin.Engine {
c.String(200, "pong")
})
// Swagger UI
// TODO: add swagger UI
// g.Static("/swagger-ui", "swagger-ui")
g.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
return g
}

Expand Down
177 changes: 177 additions & 0 deletions docs/docs.go
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,177 @@
// Package docs Code generated by swaggo/swag. DO NOT EDIT
package docs

import "github.com/swaggo/swag"

const docTemplate = `{
"schemes": {{ marshal .Schemes }},
"swagger": "2.0",
"info": {
"description": "{{escape .Description}}",
"title": "{{.Title}}",
"contact": {
"name": "Blink Labs",
"url": "https://blinklabs.io",
"email": "[email protected]"
},
"license": {
"name": "Apache 2.0",
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
},
"version": "{{.Version}}"
},
"host": "{{.Host}}",
"basePath": "{{.BasePath}}",
"paths": {
"/fcm": {
"post": {
"description": "Store a new FCM token",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"summary": "Store FCM Token",
"parameters": [
{
"description": "FCM Token Request",
"name": "body",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/push.TokenRequest"
}
}
],
"responses": {
"201": {
"description": "Created",
"schema": {
"type": "string"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/push.ErrorResponse"
}
}
}
}
},
"/fcm/{token}": {
"get": {
"description": "Get an FCM token by its value",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"summary": "Get FCM Token",
"parameters": [
{
"type": "string",
"description": "FCM Token",
"name": "token",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/push.TokenResponse"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/push.ErrorResponse"
}
}
}
},
"delete": {
"description": "Delete an FCM token by its value",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"summary": "Delete FCM Token",
"parameters": [
{
"type": "string",
"description": "FCM Token",
"name": "token",
"in": "path",
"required": true
}
],
"responses": {
"204": {
"description": "No Content",
"schema": {
"type": "string"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/push.ErrorResponse"
}
}
}
}
}
},
"definitions": {
"push.ErrorResponse": {
"type": "object",
"properties": {
"error": {
"type": "string"
}
}
},
"push.TokenRequest": {
"type": "object",
"required": [
"fcmToken"
],
"properties": {
"fcmToken": {
"type": "string"
}
}
},
"push.TokenResponse": {
"type": "object",
"properties": {
"fcmToken": {
"type": "string"
}
}
}
}
}`

// SwaggerInfo holds exported Swagger Info so clients can modify it
var SwaggerInfo = &swag.Spec{
Version: "v1",
Host: "",
BasePath: "/v1",
Schemes: []string{"http"},
Title: "Snek API",
Description: "Snek API",
InfoInstanceName: "swagger",
SwaggerTemplate: docTemplate,
}

func init() {
swag.Register(SwaggerInfo.InstanceName(), SwaggerInfo)
}
157 changes: 157 additions & 0 deletions docs/swagger.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,157 @@
{
"schemes": [
"http"
],
"swagger": "2.0",
"info": {
"description": "Snek API",
"title": "Snek API",
"contact": {
"name": "Blink Labs",
"url": "https://blinklabs.io",
"email": "[email protected]"
},
"license": {
"name": "Apache 2.0",
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
},
"version": "v1"
},
"basePath": "/v1",
"paths": {
"/fcm": {
"post": {
"description": "Store a new FCM token",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"summary": "Store FCM Token",
"parameters": [
{
"description": "FCM Token Request",
"name": "body",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/push.TokenRequest"
}
}
],
"responses": {
"201": {
"description": "Created",
"schema": {
"type": "string"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/push.ErrorResponse"
}
}
}
}
},
"/fcm/{token}": {
"get": {
"description": "Get an FCM token by its value",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"summary": "Get FCM Token",
"parameters": [
{
"type": "string",
"description": "FCM Token",
"name": "token",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/push.TokenResponse"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/push.ErrorResponse"
}
}
}
},
"delete": {
"description": "Delete an FCM token by its value",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"summary": "Delete FCM Token",
"parameters": [
{
"type": "string",
"description": "FCM Token",
"name": "token",
"in": "path",
"required": true
}
],
"responses": {
"204": {
"description": "No Content",
"schema": {
"type": "string"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/push.ErrorResponse"
}
}
}
}
}
},
"definitions": {
"push.ErrorResponse": {
"type": "object",
"properties": {
"error": {
"type": "string"
}
}
},
"push.TokenRequest": {
"type": "object",
"required": [
"fcmToken"
],
"properties": {
"fcmToken": {
"type": "string"
}
}
},
"push.TokenResponse": {
"type": "object",
"properties": {
"fcmToken": {
"type": "string"
}
}
}
}
}
Loading

0 comments on commit 3710a4f

Please sign in to comment.