feat: Add swagger spec for webhooks endpoint (#23)

Makefile

@@ -32,4 +32,7 @@ run-server:
 run-worker:
 	go run cmd/postmand/main.go worker
 
-.PHONY: lint test mock download-golang-migrate-binary db-migrate db-test-migrate run-server run-worker
+swag-init:
+	swag init -g cmd/postmand/main.go --parseDependency
+
+.PHONY: lint test mock download-golang-migrate-binary db-migrate db-test-migrate run-server run-worker swag-init

README.md

@@ -47,6 +47,23 @@ make run-migrate # create database schema
 make run-server # run the server
 ```
 
+###  Run the worker
+
+The worker is responsible to delivery content to the webhooks.
+
+#### Docker
+
+```bash
+docker run --env POSTMAND_DATABASE_URL='postgres://user:[email protected]:5432/postmand?sslmode=disable' allisson/postmand worker
+```
+
+#### Local
+
+```bash
+make run-worker
+go run cmd/postmand/main.go worker
+```
+
 ### Create a new webhook
 
 The fields delivery_attempt_timeout/retry_min_backoff/retry_max_backoff are in seconds.
@@ -116,29 +133,6 @@ curl --location --request POST 'http://localhost:8000/v1/deliveries' \
 }
 ```
 
-###  Run the worker
-
-The worker is responsible to delivery content to the webhooks.
-
-#### Docker
-
-```bash
-docker run --env POSTMAND_DATABASE_URL='postgres://user:[email protected]:5432/postmand?sslmode=disable' allisson/postmand worker
-{"level":"info","ts":1615236411.115703,"caller":"service/worker.go:74","msg":"worker-started"}
-{"level":"info","ts":1615236411.1158803,"caller":"http/server.go:60","msg":"http-server-listen-and-server"}
-{"level":"info","ts":1615236411.687701,"caller":"service/worker.go:42","msg":"worker-delivery-attempt-created","id":"d72719d6-5a79-4df7-a2c2-2029ab0e1848","webhook_id":"a6e9a525-ac5a-488c-b118-bd7327ce6d8d","delivery_id":"bc76122c-e56b-45c7-8dc3-b80a861191d5","response_status_code":200,"execution_duration":547,"success":true}
-```
-
-#### Local
-
-```bash
-make run-worker
-go run cmd/postmand/main.go worker
-{"level":"info","ts":1615236411.115703,"caller":"service/worker.go:74","msg":"worker-started"}
-{"level":"info","ts":1615236411.1158803,"caller":"http/server.go:60","msg":"http-server-listen-and-server"}
-{"level":"info","ts":1615236411.687701,"caller":"service/worker.go:42","msg":"worker-delivery-attempt-created","id":"d72719d6-5a79-4df7-a2c2-2029ab0e1848","webhook_id":"a6e9a525-ac5a-488c-b118-bd7327ce6d8d","delivery_id":"bc76122c-e56b-45c7-8dc3-b80a861191d5","response_status_code":200,"execution_duration":547,"success":true}
-```
-
 ### Get deliveries
 
 ```bash
@@ -231,6 +225,10 @@ curl --location --request GET 'http://localhost:8000/v1/delivery-attempts/d72719
 }
 ```
 
+### Swagger docs
+
+The swagger spec is available at http://localhost:8000/swagger/index.html.
+
 ### Health check
 
 The health check server is running on port defined by envvar POSTMAND_HEALTH_CHECK_HTTP_PORT (defaults to 8001).
@@ -254,4 +252,3 @@ All environment variables is defined on file local.env.
 ```
 docker build -f Dockerfile -t postmand .
 ```
-

cmd/postmand/main.go

@@ -6,13 +6,15 @@ import (
 	"time"
 
 	"github.com/allisson/go-env"
+	_ "github.com/allisson/postmand/docs"
 	"github.com/allisson/postmand/http"
 	"github.com/allisson/postmand/http/handler"
 	"github.com/allisson/postmand/repository"
 	"github.com/allisson/postmand/service"
 	"github.com/go-chi/chi/v5"
 	"github.com/jmoiron/sqlx"
 	_ "github.com/joho/godotenv/autoload"
+	httpSwagger "github.com/swaggo/http-swagger"
 	"github.com/urfave/cli/v2"
 	"go.uber.org/zap"
 )
@@ -27,6 +29,10 @@ func healthcheckServer(db *sqlx.DB, logger *zap.Logger) {
 	server.Run()
 }
 
+// @title Postmand API
+// @version 1.0
+// @description Simple webhook delivery system powered by Golang and PostgreSQL.
+// @BasePath /v1
 func main() {
 	// Setup logger
 	logger, err := zap.NewProduction()
@@ -108,6 +114,7 @@ func main() {
 				deliveryHandler := handler.NewDelivery(deliveryService, logger)
 				deliveryAttemptHandler := handler.NewDeliveryAttempt(deliveryAttemptService, logger)
 
+				httpPort := env.GetInt("POSTMAND_HTTP_PORT", 8000)
 				mux := http.NewRouter(logger)
 				mux.Route("/v1/webhooks", func(r chi.Router) {
 					r.Get("/", webhookHandler.List)
@@ -126,8 +133,11 @@ func main() {
 					r.Get("/", deliveryAttemptHandler.List)
 					r.Get("/{delivery_attempt_id}", deliveryAttemptHandler.Get)
 				})
+				mux.Get("/swagger/*", httpSwagger.Handler(
+					httpSwagger.URL("/swagger/doc.json"), //The url pointing to API definition"
+				))
 
-				server := http.NewServer(mux, env.GetInt("POSTMAND_HTTP_PORT", 8000), logger)
+				server := http.NewServer(mux, httpPort, logger)
 				server.Run()
 
 				return nil