🔒 security: harden OpenAPI middleware - fix path generation, add nil checks, improve docs

Agent-Logs-Url: https://github.com/gofiber/fiber/sessions/359aa061-8041-46a8-b6c8-46ef09f85838

Co-authored-by: gaby <835733+gaby@users.noreply.github.com>

Author: Claude

app.go

@@ -825,6 +825,7 @@ func (app *App) Description(desc string) Router {
 // Consumes assigns a request media type to the most recently added route.
 func (app *App) Consumes(typ string) Router {
 	if typ != "" {
+		typ = strings.TrimSpace(typ)
 		if _, _, err := mime.ParseMediaType(typ); err != nil || !strings.Contains(typ, "/") {
 			panic("invalid media type: " + typ)
 		}
@@ -838,6 +839,7 @@ func (app *App) Consumes(typ string) Router {
 // Produces assigns a response media type to the most recently added route.
 func (app *App) Produces(typ string) Router {
 	if typ != "" {
+		typ = strings.TrimSpace(typ)
 		if _, _, err := mime.ParseMediaType(typ); err != nil || !strings.Contains(typ, "/") {
 			panic("invalid media type: " + typ)
 		}

docs/middleware/openapi.md

@@ -26,8 +26,15 @@ import (
 After you initiate your Fiber app, you can use the following possibilities:
 
 ```go
-// Initialize default config. Register the middleware *after* all routes
-// so that the spec includes every handler.
+// Initialize default config.
+//
+// The middleware inspects the app's routes and generates the OpenAPI spec
+// the first time a matching request (for example, GET /openapi.json) is served.
+// That spec is then cached for the lifetime of the process, so any routes
+// registered after the first OpenAPI request will not appear in the spec.
+//
+// To avoid surprises, register the middleware *after* all routes have been
+// added and before you start serving traffic.
 app.Use(openapi.New())
 
 // Or extend your config for customization

middleware/openapi/openapi.go

@@ -144,12 +144,11 @@ func generateSpec(app *fiber.App, cfg *Config) openAPISpec {
 				continue
 			}
 
-			path := r.Path
+			path := convertToOpenAPIPath(r.Path, r.Params)
 			params := make([]parameter, 0, len(r.Params))
 			paramIndex := make(map[string]int, len(r.Params))
 			if len(r.Params) > 0 {
 				for _, p := range r.Params {
-					path = strings.Replace(path, ":"+p, "{"+p+"}", 1)
 					param := parameter{
 						Name:     p,
 						In:       "path",
@@ -309,7 +308,7 @@ func mergeConfigParameters(params []parameter, index map[string]int, extras []Pa
 }
 
 func appendOrReplaceParameter(params []parameter, index map[string]int, p *parameter) []parameter {
-	if p.Name == "" || p.In == "" {
+	if p == nil || p.Name == "" || p.In == "" {
 		return params
 	}
 	key := p.In + ":" + p.Name
@@ -518,3 +517,88 @@ func defaultResponseForMethod(method, mediaType string) (string, response) {
 	}
 	return status, resp
 }
+
+// convertToOpenAPIPath converts Fiber route path patterns to OpenAPI path templates.
+// It handles parameter constraints (:id<int>), wildcards (*), plus params (+), and optional markers (?).
+// Examples:
+//   - /users/:id<int> -> /users/{id}
+//   - /files/* -> /files/{wildcard}
+//   - /items/:id? -> /items/{id}
+//   - /posts/:slug+ -> /posts/{slug}
+func convertToOpenAPIPath(fiberPath string, params []string) string {
+	if len(params) == 0 && !strings.ContainsAny(fiberPath, ":*+") {
+		return fiberPath
+	}
+
+	// Build a map of parameter names for quick lookup
+	paramSet := make(map[string]struct{}, len(params))
+	for _, p := range params {
+		paramSet[p] = struct{}{}
+	}
+
+	var result strings.Builder
+	result.Grow(len(fiberPath))
+	i := 0
+	length := len(fiberPath)
+
+	for i < length {
+		ch := fiberPath[i]
+
+		switch ch {
+		case ':':
+			// Named parameter - extract name until we hit a constraint, optional marker, or delimiter
+			i++
+			paramStart := i
+			for i < length {
+				c := fiberPath[i]
+				if c == '<' || c == '?' || c == '/' || c == '-' || c == '.' {
+					break
+				}
+				i++
+			}
+			paramName := fiberPath[paramStart:i]
+
+			// Skip constraints like <int>, <regex(...)>, etc.
+			if i < length && fiberPath[i] == '<' {
+				depth := 1
+				i++ // skip '<'
+				for i < length && depth > 0 {
+					switch fiberPath[i] {
+					case '<':
+						depth++
+					case '>':
+						depth--
+					default:
+						// Other characters inside constraints are ignored
+					}
+					i++
+				}
+			}
+
+			// Skip optional marker '?'
+			if i < length && fiberPath[i] == '?' {
+				i++
+			}
+
+			// Write OpenAPI parameter placeholder
+			if paramName != "" {
+				_ = result.WriteByte('{')            //nolint:errcheck // strings.Builder.WriteByte never returns an error
+				_, _ = result.WriteString(paramName) //nolint:errcheck // strings.Builder.WriteString never returns an error
+				_ = result.WriteByte('}')            //nolint:errcheck // strings.Builder.WriteByte never returns an error
+			}
+
+		case '*', '+':
+			// Wildcard or plus param - use a generic name
+			// In Fiber, * and + are greedy params that match everything
+			// We represent them as {wildcard} or the named param if it exists
+			_, _ = result.WriteString("{wildcard}") //nolint:errcheck // strings.Builder.WriteString never returns an error
+			i++
+
+		default:
+			_ = result.WriteByte(ch) //nolint:errcheck // strings.Builder.WriteByte never returns an error
+			i++
+		}
+	}
+
+	return result.String()
+}

middleware/openapi/openapi_test.go

@@ -750,3 +750,74 @@ func Test_OpenAPI_AutoHeadExcluded(t *testing.T) {
 	require.Contains(t, ops, "get")
 	require.NotContains(t, ops, "head", "auto-generated HEAD route should be excluded")
 }
+
+func Test_ConvertToOpenAPIPath(t *testing.T) {
+	tests := []struct {
+		name       string
+		fiberPath  string
+		expectPath string
+		params     []string
+	}{
+		{
+			name:       "simple path no params",
+			fiberPath:  "/users",
+			params:     nil,
+			expectPath: "/users",
+		},
+		{
+			name:       "parameter with constraint",
+			fiberPath:  "/users/:id<int>",
+			params:     []string{"id"},
+			expectPath: "/users/{id}",
+		},
+		{
+			name:       "parameter with regex constraint",
+			fiberPath:  "/posts/:slug<regex([a-z]+)>",
+			params:     []string{"slug"},
+			expectPath: "/posts/{slug}",
+		},
+		{
+			name:       "optional parameter",
+			fiberPath:  "/items/:id?",
+			params:     []string{"id"},
+			expectPath: "/items/{id}",
+		},
+		{
+			name:       "wildcard param",
+			fiberPath:  "/files/*",
+			params:     []string{"*"},
+			expectPath: "/files/{wildcard}",
+		},
+		{
+			name:       "plus param",
+			fiberPath:  "/docs/+",
+			params:     []string{"+"},
+			expectPath: "/docs/{wildcard}",
+		},
+		{
+			name:       "multiple params with constraints",
+			fiberPath:  "/api/:version<int>/:resource/:id<int>",
+			params:     []string{"version", "resource", "id"},
+			expectPath: "/api/{version}/{resource}/{id}",
+		},
+		{
+			name:       "param with dot delimiter",
+			fiberPath:  "/files/:name.:ext",
+			params:     []string{"name", "ext"},
+			expectPath: "/files/{name}.{ext}",
+		},
+		{
+			name:       "param with dash delimiter",
+			fiberPath:  "/users/:firstName-:lastName",
+			params:     []string{"firstName", "lastName"},
+			expectPath: "/users/{firstName}-{lastName}",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := convertToOpenAPIPath(tt.fiberPath, tt.params)
+			require.Equal(t, tt.expectPath, result)
+		})
+	}
+}