add api docs

This commit is contained in:
Jonas Leder 2025-11-10 19:06:04 +01:00
commit cb31b19691
7 changed files with 216 additions and 7 deletions

View file

@ -7,10 +7,16 @@ import (
"jonasled.dev/jonasled/shelly-smoke-alamos/configuration"
)
// @Summary Webhook
// @Description Webhook for smoke detector to trigger alarm
// @Tags webhook
// @Success 200
// @Param secret path string true "Smoke Detector secret"
// @Router /api/webhook/{secret} [get]
func initWebhook() {
conf := configuration.ReadConfig()
R.GET("/api/webhook/:id", func(ctx *gin.Context) {
id := ctx.Param("id")
R.GET("/api/webhook/:secret", func(ctx *gin.Context) {
id := ctx.Param("secret")
for _, sensor := range conf.SmokeDetectors {
if sensor.ID == id {

View file

@ -6,18 +6,16 @@ import (
ginSwagger "github.com/swaggo/gin-swagger"
ginlogrus "github.com/toorop/gin-logrus"
"jonasled.dev/jonasled/go-libs/log"
_ "jonasled.dev/jonasled/shelly-smoke-alamos/docs"
)
// gin-swagger middleware
// swagger embed files
var R *gin.Engine
func Init() {
log.Log.Info("Initializing webserver")
R = gin.New()
R.Use(ginlogrus.Logger(log.Log), gin.Recovery())
R.GET("/api/doc/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) // swagger api docs
R.GET("/api/docs/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) // swagger api docs
initGeneralRoutes()
initWebhook()
}

103
docs/docs.go Normal file
View file

@ -0,0 +1,103 @@
// GENERATED BY THE COMMAND ABOVE; DO NOT EDIT
// This file was generated by swaggo/swag at
// 2025-11-10 19:05:44.629181352 +0100 CET m=+2.341595534
package docs
import (
"bytes"
"github.com/alecthomas/template"
"github.com/swaggo/swag"
)
var doc = `{
"swagger": "2.0",
"info": {
"description": "{{.Description}}",
"title": "{{.Title}}",
"contact": {},
"license": {},
"version": "{{.Version}}"
},
"host": "{{.Host}}",
"basePath": "{{.BasePath}}",
"paths": {
"/api/health": {
"get": {
"description": "returns always OK if the application is running",
"tags": [
"health"
],
"summary": "Readiness Probe",
"responses": {
"200": {}
}
}
},
"/api/health/liveness": {
"get": {
"description": "returns OK if all services are connected",
"tags": [
"health"
],
"summary": "Liveness Probe",
"responses": {
"200": {}
}
}
},
"/api/webhook/{secret}": {
"get": {
"description": "Webhook for smoke detector to trigger alarm",
"tags": [
"webhook"
],
"summary": "Webhook",
"parameters": [
{
"type": "string",
"description": "Smoke Detector secret",
"name": "secret",
"in": "path",
"required": true
}
],
"responses": {
"200": {}
}
}
}
}
}`
type swaggerInfo struct {
Version string
Host string
BasePath string
Title string
Description string
}
// SwaggerInfo holds exported Swagger Info so clients can modify it
var SwaggerInfo swaggerInfo
type s struct{}
func (s *s) ReadDoc() string {
t, err := template.New("swagger_info").Parse(doc)
if err != nil {
return doc
}
var tpl bytes.Buffer
if err := t.Execute(&tpl, SwaggerInfo); err != nil {
return doc
}
return tpl.String()
}
func init() {
swag.Register(swag.Name, &s{})
}

59
docs/swagger.json Normal file
View file

@ -0,0 +1,59 @@
{
"swagger": "2.0",
"info": {
"description": "{{.Description}}",
"title": "{{.Title}}",
"contact": {},
"license": {},
"version": "{{.Version}}"
},
"host": "{{.Host}}",
"basePath": "{{.BasePath}}",
"paths": {
"/api/health": {
"get": {
"description": "returns always OK if the application is running",
"tags": [
"health"
],
"summary": "Readiness Probe",
"responses": {
"200": {}
}
}
},
"/api/health/liveness": {
"get": {
"description": "returns OK if all services are connected",
"tags": [
"health"
],
"summary": "Liveness Probe",
"responses": {
"200": {}
}
}
},
"/api/webhook/{secret}": {
"get": {
"description": "Webhook for smoke detector to trigger alarm",
"tags": [
"webhook"
],
"summary": "Webhook",
"parameters": [
{
"type": "string",
"description": "Smoke Detector secret",
"name": "secret",
"in": "path",
"required": true
}
],
"responses": {
"200": {}
}
}
}
}
}

40
docs/swagger.yaml Normal file
View file

@ -0,0 +1,40 @@
basePath: '{{.BasePath}}'
host: '{{.Host}}'
info:
contact: {}
description: '{{.Description}}'
license: {}
title: '{{.Title}}'
version: '{{.Version}}'
paths:
/api/health:
get:
description: returns always OK if the application is running
responses:
"200": {}
summary: Readiness Probe
tags:
- health
/api/health/liveness:
get:
description: returns OK if all services are connected
responses:
"200": {}
summary: Liveness Probe
tags:
- health
/api/webhook/{secret}:
get:
description: Webhook for smoke detector to trigger alarm
parameters:
- description: Smoke Detector secret
in: path
name: secret
required: true
type: string
responses:
"200": {}
summary: Webhook
tags:
- webhook
swagger: "2.0"

3
go.mod
View file

@ -3,10 +3,12 @@ module jonasled.dev/jonasled/shelly-smoke-alamos
go 1.25.3
require (
github.com/alecthomas/template v0.0.0-20190718012654-fb15b899a751
github.com/gin-gonic/gin v1.11.0
github.com/joho/godotenv v1.5.1
github.com/swaggo/files v1.0.1
github.com/swaggo/gin-swagger v1.6.1
github.com/swaggo/swag v1.8.12
github.com/toorop/gin-logrus v0.0.0-20210225092905-2c785434f26f
go.yaml.in/yaml/v3 v3.0.4
jonasled.dev/jonasled/go-libs v0.0.3
@ -42,7 +44,6 @@ require (
github.com/quic-go/qpack v0.5.1 // indirect
github.com/quic-go/quic-go v0.54.0 // indirect
github.com/sirupsen/logrus v1.9.3 // indirect
github.com/swaggo/swag v1.8.12 // indirect
github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
github.com/ugorji/go/codec v1.3.0 // indirect
go.uber.org/mock v0.5.0 // indirect

2
go.sum
View file

@ -4,6 +4,8 @@ github.com/PuerkitoBio/purell v1.1.1 h1:WEQqlqaGbrPkxLJWfBwQmfEAE1Z7ONdDLqrN38tN
github.com/PuerkitoBio/purell v1.1.1/go.mod h1:c11w/QuzBsJSee3cPx9rAFu61PvFxuPbtSwDGJws/X0=
github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578 h1:d+Bc7a5rLufV/sSk/8dngufqelfh6jnri85riMAaF/M=
github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578/go.mod h1:uGdkoq3SwY9Y+13GIhn11/XLaGBb4BfwItxLd5jeuXE=
github.com/alecthomas/template v0.0.0-20190718012654-fb15b899a751 h1:JYp7IbQjafoB+tBA3gMyHYHrpOtNuDiK/uB5uXxq5wM=
github.com/alecthomas/template v0.0.0-20190718012654-fb15b899a751/go.mod h1:LOuyumcjzFXgccqObfd/Ljyb9UuFJ6TxHnclSeseNhc=
github.com/bytedance/sonic v1.14.0 h1:/OfKt8HFw0kh2rj8N0F6C/qPGRESq0BbaNZgcNXXzQQ=
github.com/bytedance/sonic v1.14.0/go.mod h1:WoEbx8WTcFJfzCe0hbmyTGrfjt8PzNEBdxlNUO24NhA=
github.com/bytedance/sonic/loader v0.3.0 h1:dskwH8edlzNMctoruo8FPTJDF3vLtDT0sXZwvZJyqeA=