feat: enhance API with OpenAPI support and refactor endpoint handling

Author: sattvikc

.gitignore

@@ -19,4 +19,6 @@
 
 # Go workspace file
 go.work
-tmp/
+tmp/
+
+coverage.*

Makefile

@@ -3,4 +3,6 @@ test:
 
 test-coverage:
 	go test -coverpkg ./... -cover -coverprofile=coverage.out -v ./...
-	go tool cover -html=coverage.out
+	go tool cover -html=coverage.out -o=coverage.html
+	go tool cover -func=coverage.out -o=coverage.out
+	grep -v '100.0%$$' coverage.out

README.md

@@ -37,16 +37,14 @@ Swagger UI will be instantly available on `http://localhost:8000/try` and the sw
 To add routes, call the appropriate methods on the app.
 
 ```go
-app.GET(path, tags, handlers...)
-app.POST(path, tags, handlers...)
-app.PUT(path, tags, handlers...)
+app.GET(path, handlers...)
+app.POST(path, handlers...)
+app.PUT(path, handlers...)
 // and so on
 ```
 
 path: `string` - path to handle
 
-tags: `[]string` - swagger tags
-
 handlers: `[]interface{}` - functions that handle the request
 
 ### Handler
@@ -125,6 +123,6 @@ type InputType struct {
 type InputType struct {
     Form struct {
         UploadedFile *multipart.FileHeader `form:"file"`
-    }
+    } `body:"multipart"`
 }
 ```

ROADMAP.md

@@ -3,7 +3,15 @@
 ## Features
 
 - [ ] Configurable Swagger Spec
+- [ ] Swagger features
+  - [ ] Info
+  - [ ] Servers
+  - [ ] Security Scheme
+  - [ ] Tags
+  - [ ] Endpoint: Summary, Description, OperationId
+
 - [ ] Swagger descriptions
+- [ ] Input / Output validation
 - [ ] Response Headers
 - [ ] Non-json responses
 - [ ] Middleware
@@ -13,8 +21,8 @@
 
 ## Framework support
 
-- [-] Gin - https://github.com/gin-gonic/gin - 83k
-- [-] Fiber - https://github.com/gofiber/fiber - 37k
+- [x] Gin - https://github.com/gin-gonic/gin - 83k
+- [x] Fiber - https://github.com/gofiber/fiber - 37k
 - [ ] Beego - https://github.com/beego/beego - 32k
 - [ ] Echo - https://github.com/labstack/echo - 31k
 - [ ] go-zero - https://github.com/zeromicro/go-zero - 31k

app.go

@@ -1,110 +1,96 @@
 package simplapi
 
 import (
+	"net/http"
+
 	"github.com/go-simpl/simplapi/pkg/framework"
 	"github.com/go-simpl/simplapi/pkg/handler"
-	"github.com/go-simpl/simplapi/pkg/swagger"
+	"github.com/go-simpl/simplapi/pkg/spec"
 )
 
 type App struct {
-	framework   framework.Framework
-	swaggerJson map[string]interface{}
+	framework framework.Framework
+	spec      *spec.Spec
+
+	endpoints []*Endpoint
 }
 
 func New(frameworkName ...string) *App {
 	frameworkName = append(frameworkName, "fiber")
 
 	s := &App{
 		framework: framework.GetFramework(frameworkName[0]),
-		swaggerJson: map[string]interface{}{
-			"openapi": "3.0.0",
-			"info": map[string]interface{}{
-				"title":   "SimpleAPI",
-				"version": "1.0.0",
-			},
-			"paths": map[string]interface{}{},
-		},
+		spec:      spec.New(),
+		endpoints: []*Endpoint{},
 	}
-	addSwaggerRoutes(s)
+	addOpenAPIRoutes(s)
 	return s
 }
 
 func (s *App) GetApp() framework.Framework {
 	return s.framework
 }
 
-func (s *App) ListenAndServe(addr string) error {
-	return s.framework.ListenAndServe(addr)
+func (s *App) GET(path string, handlers ...interface{}) *Endpoint {
+	endpoint := newEndpoint(http.MethodGet, path, handlers...)
+	s.addEndpoint(endpoint)
+	return endpoint
 }
 
-func (s *App) createHandler(handlers ...interface{}) framework.FrameworkHandler {
-	// Reverse the handlers slice
-	for i, j := 0, len(handlers)-1; i < j; i, j = i+1, j-1 {
-		handlers[i], handlers[j] = handlers[j], handlers[i]
-	}
-
-	var nextHandler framework.FrameworkHandler = nil
-	for _, h := range handlers {
-		nextHandler = handler.WrapHandler(h, nextHandler)
-	}
-
-	return nextHandler
-}
-
-func (s *App) GET(path string, tags []string, handlers ...interface{}) {
-	s.framework.GET(path, s.createHandler(handlers...))
-	s.addToSwagger(path, "get", handlers, tags)
+func (s *App) POST(path string, handlers ...interface{}) *Endpoint {
+	endpoint := newEndpoint(http.MethodPost, path, handlers...)
+	s.addEndpoint(endpoint)
+	return endpoint
 }
 
-func (s *App) POST(path string, tags []string, handlers ...interface{}) {
-	s.framework.POST(path, s.createHandler(handlers...))
-	s.addToSwagger(path, "post", handlers, tags)
+func (s *App) PUT(path string, handlers ...interface{}) *Endpoint {
+	endpoint := newEndpoint(http.MethodPut, path, handlers...)
+	s.addEndpoint(endpoint)
+	return endpoint
 }
 
-func (s *App) PUT(path string, tags []string, handlers ...interface{}) {
-	s.framework.PUT(path, s.createHandler(handlers...))
-	s.addToSwagger(path, "put", handlers, tags)
+func (s *App) DELETE(path string, handlers ...interface{}) *Endpoint {
+	endpoint := newEndpoint(http.MethodDelete, path, handlers...)
+	s.addEndpoint(endpoint)
+	return endpoint
 }
 
-func (s *App) PATCH(path string, tags []string, handlers ...interface{}) {
-	s.framework.PATCH(path, s.createHandler(handlers...))
-	s.addToSwagger(path, "patch", handlers, tags)
+func (s *App) PATCH(path string, handlers ...interface{}) *Endpoint {
+	endpoint := newEndpoint(http.MethodPatch, path, handlers...)
+	s.addEndpoint(endpoint)
+	return endpoint
 }
 
-func (s *App) DELETE(path string, tags []string, handlers ...interface{}) {
-	s.framework.DELETE(path, s.createHandler(handlers...))
-	s.addToSwagger(path, "delete", handlers, tags)
-}
-
-func (s *App) addToSwagger(path string, method string, handlers []interface{}, tags []string) {
-	if path == "/try" || path == "/openapi.json" {
-		return
+func (s *App) Sync() {
+	for _, e := range s.endpoints {
+		s.framework.Register(e.path, e.method, s.createHandler(e.handlers...))
+		if e.addToSpec {
+			s.spec.Register(e.path, e.method, e.handlers...)
+		}
 	}
+}
 
-	definition := map[string]interface{}{
-		"parameters": []interface{}{},
-		"responses":  map[string]interface{}{},
-		"tags":       tags,
-	}
+func (s *App) ListenAndServe(addr string) error {
+	// Actual registration of endpoints happen here
+	s.Sync()
 
-	if method != "get" {
-		definition["requestBody"] = map[string]interface{}{}
-	}
+	return s.framework.ListenAndServe(addr)
+}
 
-	for _, handler := range handlers {
-		swagger.UpdateDefinitionUsingHandler(definition, handler)
-	}
+func (s *App) addEndpoint(endpoint *Endpoint) {
+	s.endpoints = append(s.endpoints, endpoint)
+}
 
-	if _, ok := s.swaggerJson["paths"].(map[string]interface{})[path]; !ok {
-		s.swaggerJson["paths"].(map[string]interface{})[path] = map[string]interface{}{}
+func (s *App) createHandler(handlers ...interface{}) framework.FrameworkHandler {
+	// Reverse the handlers slice
+	for i, j := 0, len(handlers)-1; i < j; i, j = i+1, j-1 {
+		handlers[i], handlers[j] = handlers[j], handlers[i]
 	}
 
-	if _, ok := s.swaggerJson["paths"].(map[string]interface{})[path].(map[string]interface{})[method]; !ok {
-		s.swaggerJson["paths"].(map[string]interface{})[path].(map[string]interface{})[method] = definition
+	var nextHandler framework.FrameworkHandler = nil
+	for _, h := range handlers {
+		nextHandler = handler.WrapHandler(h, nextHandler)
 	}
 
-	responses := definition["responses"].(map[string]interface{})
-	for _, handler := range handlers {
-		swagger.UpdateResponseDefinitionUsingHandler(responses, handler)
-	}
+	return nextHandler
 }

endpoint.go

@@ -0,0 +1,46 @@
+package simplapi
+
+type Endpoint struct {
+	method      string
+	path        string
+	tags        []string
+	summary     string
+	description string
+	operationId string
+	handlers    []interface{}
+	addToSpec   bool
+}
+
+func newEndpoint(method string, path string, handlers ...interface{}) *Endpoint {
+	return &Endpoint{
+		method:    method,
+		path:      path,
+		handlers:  handlers,
+		addToSpec: true,
+	}
+}
+
+func (e *Endpoint) WithTag(tag string) *Endpoint {
+	e.tags = append(e.tags, tag)
+	return e
+}
+
+func (e *Endpoint) WithSummary(summary string) *Endpoint {
+	e.summary = summary
+	return e
+}
+
+func (e *Endpoint) WithDescription(description string) *Endpoint {
+	e.description = description
+	return e
+}
+
+func (e *Endpoint) WithOperationId(operationId string) *Endpoint {
+	e.operationId = operationId
+	return e
+}
+
+func (e *Endpoint) WithoutSpec() *Endpoint {
+	e.addToSpec = false
+	return e
+}

go.mod

@@ -3,6 +3,7 @@ module github.com/go-simpl/simplapi
 go 1.24
 
 require (
+	github.com/getkin/kin-openapi v0.132.0
 	github.com/gin-gonic/gin v1.10.1
 	github.com/gofiber/fiber/v2 v2.52.9
 	github.com/stretchr/testify v1.10.0
@@ -17,21 +18,29 @@ require (
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/gabriel-vasile/mimetype v1.4.3 // indirect
 	github.com/gin-contrib/sse v0.1.0 // indirect
+	github.com/go-openapi/jsonpointer v0.21.0 // indirect
+	github.com/go-openapi/swag v0.23.0 // indirect
 	github.com/go-playground/locales v0.14.1 // indirect
 	github.com/go-playground/universal-translator v0.18.1 // indirect
 	github.com/go-playground/validator/v10 v10.20.0 // indirect
 	github.com/goccy/go-json v0.10.2 // indirect
 	github.com/google/uuid v1.6.0 // indirect
+	github.com/josharian/intern v1.0.0 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
 	github.com/klauspost/compress v1.17.9 // indirect
 	github.com/klauspost/cpuid/v2 v2.2.7 // indirect
 	github.com/leodido/go-urn v1.4.0 // indirect
+	github.com/mailru/easyjson v0.7.7 // indirect
 	github.com/mattn/go-colorable v0.1.13 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/mattn/go-runewidth v0.0.16 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/modern-go/reflect2 v1.0.2 // indirect
+	github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 // indirect
+	github.com/oasdiff/yaml v0.0.0-20250309154309-f31be36b4037 // indirect
+	github.com/oasdiff/yaml3 v0.0.0-20250309153720-d2182401db90 // indirect
 	github.com/pelletier/go-toml/v2 v2.2.2 // indirect
+	github.com/perimeterx/marshmallow v1.1.5 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/rivo/uniseg v0.2.0 // indirect
 	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect