docs: enhance documentation with detailed comments for API builder, endpoint, and OpenAPI spec functionalities

Author: sattvikc

app.go

@@ -1,3 +1,6 @@
+// Package simplapi provides a declarative HTTP API builder with optional
+// OpenAPI 3.1 spec generation. Use New with options to create an App, then
+// register routes via GET, POST, etc. and call ListenAndServe.
 package simplapi
 
 import (
@@ -8,38 +11,46 @@ import (
 	"github.com/go-simpl/simplapi/pkg/spec"
 )
 
+// App is the main API builder. It holds a framework adapter, optional OpenAPI
+// spec, and a list of endpoints that are registered on Sync or ListenAndServe.
 type App struct {
 	framework framework.Framework
 	spec      *spec.Spec
 
 	endpoints []*Endpoint
 }
 
+// AppConfig holds options applied by AppOption functions during New.
 type AppConfig struct {
 	framework framework.Framework
 	spec      *spec.Spec
 }
 
+// AppOption configures an App at construction time (e.g. WithCreateFramework, WithAutoOpenAPISpec).
 type AppOption func(*AppConfig)
 
+// WithCreateFramework creates an App that uses the named framework (e.g. "fiber", "gin").
 func WithCreateFramework(frameworkName string) AppOption {
 	return func(c *AppConfig) {
 		c.framework = framework.GetFramework(frameworkName)
 	}
 }
 
+// WithFramework creates an App that uses the given framework instance.
 func WithFramework(framework framework.Framework) AppOption {
 	return func(c *AppConfig) {
 		c.framework = framework
 	}
 }
 
+// WithAutoOpenAPISpec enables OpenAPI 3.1 spec generation and built-in doc routes. basePkgName is stripped from schema type names.
 func WithAutoOpenAPISpec(basePkgName string) AppOption {
 	return func(c *AppConfig) {
 		c.spec = spec.New(basePkgName)
 	}
 }
 
+// New creates an App with the given options. If WithAutoOpenAPISpec is used, doc routes are registered immediately.
 func New(opts ...AppOption) *App {
 	config := &AppConfig{}
 	for _, opt := range opts {
@@ -57,40 +68,48 @@ func New(opts ...AppOption) *App {
 	return s
 }
 
+// GetApp returns the underlying framework (e.g. for middleware or testing).
 func (s *App) GetApp() framework.Framework {
 	return s.framework
 }
 
+// GET registers a GET route; returns an Endpoint for fluent options (WithTag, WithoutSpec, etc.).
 func (s *App) GET(path string, handlers ...interface{}) *Endpoint {
 	endpoint := newEndpoint(http.MethodGet, path, handlers...)
 	s.addEndpoint(endpoint)
 	return endpoint
 }
 
+// POST registers a POST route; returns an Endpoint for fluent options.
 func (s *App) POST(path string, handlers ...interface{}) *Endpoint {
 	endpoint := newEndpoint(http.MethodPost, path, handlers...)
 	s.addEndpoint(endpoint)
 	return endpoint
 }
 
+// PUT registers a PUT route; returns an Endpoint for fluent options.
 func (s *App) PUT(path string, handlers ...interface{}) *Endpoint {
 	endpoint := newEndpoint(http.MethodPut, path, handlers...)
 	s.addEndpoint(endpoint)
 	return endpoint
 }
 
+// DELETE registers a DELETE route; returns an Endpoint for fluent options.
 func (s *App) DELETE(path string, handlers ...interface{}) *Endpoint {
 	endpoint := newEndpoint(http.MethodDelete, path, handlers...)
 	s.addEndpoint(endpoint)
 	return endpoint
 }
 
+// PATCH registers a PATCH route; returns an Endpoint for fluent options.
 func (s *App) PATCH(path string, handlers ...interface{}) *Endpoint {
 	endpoint := newEndpoint(http.MethodPatch, path, handlers...)
 	s.addEndpoint(endpoint)
 	return endpoint
 }
 
+// Sync registers all endpoints with the framework and (if enabled) the OpenAPI spec.
+// Registration is deferred until Sync or ListenAndServe so fluent options (WithTag, etc.) are applied first.
 func (s *App) Sync() {
 	for _, e := range s.endpoints {
 		s.framework.Register(e.path, e.method, s.createHandler(e.handlers...))
@@ -100,8 +119,8 @@ func (s *App) Sync() {
 	}
 }
 
+// ListenAndServe registers all endpoints with the framework then starts the server.
 func (s *App) ListenAndServe(addr string) error {
-	// Actual registration of endpoints happen here
 	s.Sync()
 
 	return s.framework.ListenAndServe(addr)
@@ -112,7 +131,7 @@ func (s *App) addEndpoint(endpoint *Endpoint) {
 }
 
 func (s *App) createHandler(handlers ...interface{}) framework.FrameworkHandler {
-	// Reverse the handlers slice
+	// Reverse so the first handler in the chain is outermost (middleware), last is innermost (route handler).
 	for i, j := 0, len(handlers)-1; i < j; i, j = i+1, j-1 {
 		handlers[i], handlers[j] = handlers[j], handlers[i]
 	}

endpoint.go

@@ -1,5 +1,7 @@
 package simplapi
 
+// Endpoint is the fluent builder for a single route. Use WithTag, WithSummary, etc.,
+// or WithoutSpec to omit it from the OpenAPI spec.
 type Endpoint struct {
 	method      string
 	path        string
@@ -40,6 +42,7 @@ func (e *Endpoint) WithOperationId(operationId string) *Endpoint {
 	return e
 }
 
+// WithoutSpec marks this route so it is not added to the OpenAPI spec (e.g. for internal doc routes).
 func (e *Endpoint) WithoutSpec() *Endpoint {
 	e.addToSpec = false
 	return e

errors/errors.go

@@ -1,9 +1,12 @@
+// Package errors defines error types used by simplapi. TypeError is returned for
+// handler input binding failures and is sent as HTTP 422 with a JSON body.
 package errors
 
 import (
 	"fmt"
 )
 
+// TypeError represents a validation or parsing error for a specific field during handler input binding.
 type TypeError struct {
 	FieldName string `json:"fieldName"`
 	Message   string `json:"message"`

openapi.go

@@ -81,6 +81,8 @@ const redocUI = `<!DOCTYPE html>
   </body>
 </html>`
 
+// addOpenAPIRoutes registers built-in doc routes when WithAutoOpenAPISpec is used:
+// /_try/swagger, /_try/stoplight, /_try/redoc, and /openapi.json. These are internal and not in the main API spec.
 func addOpenAPIRoutes(app *App) {
 	// TODO make the routes configurable
 	app.GET("/_try/swagger", func() (*types.HTMLResponse, error) {

pkg/context/context.go

@@ -1,28 +1,35 @@
+// Package context provides a request-scoped key-value store passed into handlers.
 package context
 
+// Context holds data for the duration of a request. Handlers can Set/Get values to pass data along the chain.
 type Context struct {
 	data map[string]any
 }
 
+// New returns a new empty request context.
 func New() *Context {
 	return &Context{
 		data: make(map[string]any),
 	}
 }
 
+// Set stores a value in the context for this request.
 func (c *Context) Set(key string, value any) {
 	c.data[key] = value
 }
 
+// Get returns the value for key, or nil if not set.
 func (c *Context) Get(key string) any {
 	return c.data[key]
 }
 
+// Contains reports whether key is set in the context.
 func (c *Context) Contains(key string) bool {
 	_, ok := c.data[key]
 	return ok
 }
 
+// Delete removes key from the context.
 func (c *Context) Delete(key string) {
 	delete(c.data, key)
 }

pkg/framework/fiberframework/framework.go

@@ -26,6 +26,7 @@ func (f *fiberFramework) GetNativeApp() interface{} {
 	return f.app
 }
 
+// GetOpenAPICompatiblePathPattern converts Fiber's :param syntax to OpenAPI's {param} for the spec.
 func (f *fiberFramework) GetOpenAPICompatiblePathPattern(path string) string {
 	pathParts := strings.Split(path, "/")
 	for i, part := range pathParts {

pkg/framework/fiberv3framework/framework.go

@@ -26,6 +26,7 @@ func (f *fiberV3Framework) GetNativeApp() interface{} {
 	return f.app
 }
 
+// GetOpenAPICompatiblePathPattern converts Fiber's :param syntax to OpenAPI's {param} for the spec.
 func (f *fiberV3Framework) GetOpenAPICompatiblePathPattern(path string) string {
 	pathParts := strings.Split(path, "/")
 	for i, part := range pathParts {

pkg/framework/ginframework/framework.go

@@ -27,6 +27,7 @@ func (g *ginFramework) GetNativeApp() interface{} {
 	return g.engine
 }
 
+// GetOpenAPICompatiblePathPattern returns path unchanged for the OpenAPI spec.
 func (g *ginFramework) GetOpenAPICompatiblePathPattern(path string) string {
 	return path
 }

pkg/framework/iface.go

@@ -1,3 +1,5 @@
+// Package framework defines the abstraction over HTTP frameworks (Fiber, Gin, etc.).
+// Implementations register via RegisterFramework in init(); the App uses GetFramework by name.
 package framework
 
 import (
@@ -7,6 +9,7 @@ import (
 	"github.com/go-simpl/simplapi/pkg/context"
 )
 
+// Framework is the interface that each backend (Fiber, Gin, etc.) must implement.
 type Framework interface {
 	Register(path string, method string, handler FrameworkHandler)
 
@@ -19,8 +22,10 @@ type Framework interface {
 	TestRequest(req *http.Request) (*http.Response, error)
 }
 
+// FrameworkHandler is the function type that the framework calls for each request.
 type FrameworkHandler func(req FrameworkRequest, res FrameworkResponse, ctx *context.Context) error
 
+// FrameworkRequest abstracts reading body, params, headers, etc. from the underlying framework.
 type FrameworkRequest interface {
 	ParseJSONBody(target interface{}) error
 	GetHeader(key string) string
@@ -31,6 +36,7 @@ type FrameworkRequest interface {
 	GetFile(key string) (*multipart.FileHeader, error)
 }
 
+// FrameworkResponse abstracts writing status, headers, and body to the underlying framework.
 type FrameworkResponse interface {
 	SetHeader(key string, value string)
 	SetCookie(cookie http.Cookie)

pkg/framework/registration.go

@@ -1,15 +1,18 @@
 package framework
 
+// availableFrameworks is populated by each framework's init() (fiber, gin, fiberv3, etc.).
 var availableFrameworks map[string]func() Framework
 
 func init() {
 	availableFrameworks = map[string]func() Framework{}
 }
 
+// RegisterFramework registers a framework by name. Called from framework packages in init().
 func RegisterFramework(name string, factory func() Framework) {
 	availableFrameworks[name] = factory
 }
 
+// GetFramework returns the framework instance for the given name. Panics if not registered.
 func GetFramework(name string) Framework {
 	factory, ok := availableFrameworks[name]
 	if !ok {