Errors can be declared globally and route per route

.golangci.yml

@@ -15,6 +15,7 @@ linters:
     - ineffassign
     - staticcheck
     - unused
+    - usestdlibvars
 
 linters-settings:
   gofumpt:

errors.go

@@ -16,19 +16,19 @@ type ErrorWithStatus interface {
 
 // HTTPError is the error response used by the serialization part of the framework.
 type HTTPError struct {
-	Err      error       `json:"-" xml:"-"`                               // Developer readable error message. Not shown to the user to avoid security leaks.
-	Type     string      `json:"type,omitempty" xml:"type,omitempty"`     // URL of the error type. Can be used to lookup the error in a documentation
-	Title    string      `json:"title,omitempty" xml:"title,omitempty"`   // Short title of the error
-	Status   int         `json:"status,omitempty" xml:"status,omitempty"` // HTTP status code. If using a different type than [HTTPError], for example [BadRequestError], this will be automatically overridden after Fuego error handling.
-	Detail   string      `json:"detail,omitempty" xml:"detail,omitempty"` // Human readable error message
+	Err      error       `json:"-" xml:"-"`                                                                                                                   // Developer readable error message. Not shown to the user to avoid security leaks.
+	Type     string      `json:"type,omitempty" xml:"type,omitempty" description:"URL of the error type. Can be used to lookup the error in a documentation"` // URL of the error type. Can be used to lookup the error in a documentation
+	Title    string      `json:"title,omitempty" xml:"title,omitempty" description:"Short title of the error"`                                                // Short title of the error
+	Status   int         `json:"status,omitempty" xml:"status,omitempty" description:"HTTP status code" example:"403"`                                        // HTTP status code. If using a different type than [HTTPError], for example [BadRequestError], this will be automatically overridden after Fuego error handling.
+	Detail   string      `json:"detail,omitempty" xml:"detail,omitempty" description:"Human readable error message"`                                          // Human readable error message
 	Instance string      `json:"instance,omitempty" xml:"instance,omitempty"`
 	Errors   []ErrorItem `json:"errors,omitempty" xml:"errors,omitempty"`
 }
 
 type ErrorItem struct {
-	Name   string         `json:"name"`
-	Reason string         `json:"reason"`
-	More   map[string]any `json:"more,omitempty"`
+	Name   string         `json:"name" xml:"name" description:"For example, name of the parameter that caused the error"`
+	Reason string         `json:"reason" xml:"reason" description:"Human readable error message"`
+	More   map[string]any `json:"more,omitempty" xml:"more,omitempty" description:"Additional information about the error"`
 }
 
 func (e HTTPError) Error() string {

examples/full-app-gourmet/server/server.go

@@ -23,13 +23,16 @@ func (rs Ressources) Setup(
 		fuego.WithAutoAuth(controller.LoginFunc),
 		fuego.WithTemplateFS(templates.FS),
 		fuego.WithTemplateGlobs("**/*.html", "**/**/*.html"),
+		fuego.WithGlobalResponseTypes(http.StatusForbidden, "Forbidden"),
 	}
 
 	options = append(serverOptions, options...)
 
 	// Create server with some options
 	app := fuego.NewServer(options...)
 
+	app.OpenApiSpec.Info.Title = "Gourmet API"
+
 	rs.API.Security = app.Security
 
 	// Register middlewares (functions that will be executed before AND after the controllers, in the order they are registered)

examples/full-app-gourmet/views/views.go

@@ -1,6 +1,7 @@
 package views
 
 import (
+	"net/http"
 	"os"
 
 	"github.com/go-fuego/fuego"
@@ -24,7 +25,7 @@ func (rs Ressource) Routes(s *fuego.Server) {
 
 	// Public Chunks
 	fuego.Get(s, "/recipes-list", rs.showRecipesList)
-	fuego.Get(s, "/search", rs.searchRecipes)
+	fuego.Get(s, "/search", rs.searchRecipes).AddError(http.StatusUnauthorized, "Authorization Error").AddError(500, "My Server Error")
 	fuego.Get(s, "/ingredients/preselect-unit", rs.unitPreselected).QueryParam("id", "")
 
 	// Admin Pages

examples/petstore/lib/testdata/doc/openapi.golden.json

@@ -36,6 +36,56 @@
 			}
 		},
 		"schemas": {
+			"HTTPError": {
+				"description": "HTTPError schema",
+				"properties": {
+					"detail": {
+						"description": "Human readable error message",
+						"nullable": true,
+						"type": "string"
+					},
+					"errors": {
+						"items": {
+							"properties": {
+								"more": {
+									"additionalProperties": {},
+									"type": "object"
+								},
+								"name": {
+									"type": "string"
+								},
+								"reason": {
+									"type": "string"
+								}
+							},
+							"type": "object"
+						},
+						"nullable": true,
+						"type": "array"
+					},
+					"instance": {
+						"nullable": true,
+						"type": "string"
+					},
+					"status": {
+						"description": "HTTP status code",
+						"example": 403,
+						"nullable": true,
+						"type": "integer"
+					},
+					"title": {
+						"description": "Short title of the error",
+						"nullable": true,
+						"type": "string"
+					},
+					"type": {
+						"description": "URL of the error type. Can be used to lookup the error in a documentation",
+						"nullable": true,
+						"type": "string"
+					}
+				},
+				"type": "object"
+			},
 			"Pets": {
 				"description": "Pets schema",
 				"properties": {
@@ -138,6 +188,26 @@
 						},
 						"description": "OK"
 					},
+					"400": {
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/HTTPError"
+								}
+							}
+						},
+						"description": "Bad Request _(validation or deserialization error)_"
+					},
+					"500": {
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/HTTPError"
+								}
+							}
+						},
+						"description": "Internal Server Error _(panics)_"
+					},
 					"default": {
 						"description": ""
 					}
@@ -169,6 +239,26 @@
 						},
 						"description": "OK"
 					},
+					"400": {
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/HTTPError"
+								}
+							}
+						},
+						"description": "Bad Request _(validation or deserialization error)_"
+					},
+					"500": {
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/HTTPError"
+								}
+							}
+						},
+						"description": "Internal Server Error _(panics)_"
+					},
 					"default": {
 						"description": ""
 					}
@@ -210,6 +300,26 @@
 						},
 						"description": "OK"
 					},
+					"400": {
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/HTTPError"
+								}
+							}
+						},
+						"description": "Bad Request _(validation or deserialization error)_"
+					},
+					"500": {
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/HTTPError"
+								}
+							}
+						},
+						"description": "Internal Server Error _(panics)_"
+					},
 					"default": {
 						"description": ""
 					}
@@ -250,6 +360,26 @@
 						},
 						"description": "OK"
 					},
+					"400": {
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/HTTPError"
+								}
+							}
+						},
+						"description": "Bad Request _(validation or deserialization error)_"
+					},
+					"500": {
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/HTTPError"
+								}
+							}
+						},
+						"description": "Internal Server Error _(panics)_"
+					},
 					"default": {
 						"description": ""
 					}
@@ -288,6 +418,26 @@
 						},
 						"description": "OK"
 					},
+					"400": {
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/HTTPError"
+								}
+							}
+						},
+						"description": "Bad Request _(validation or deserialization error)_"
+					},
+					"500": {
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/HTTPError"
+								}
+							}
+						},
+						"description": "Internal Server Error _(panics)_"
+					},
 					"default": {
 						"description": ""
 					}
@@ -329,6 +479,26 @@
 						},
 						"description": "OK"
 					},
+					"400": {
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/HTTPError"
+								}
+							}
+						},
+						"description": "Bad Request _(validation or deserialization error)_"
+					},
+					"500": {
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/HTTPError"
+								}
+							}
+						},
+						"description": "Internal Server Error _(panics)_"
+					},
 					"default": {
 						"description": ""
 					}

mux.go

@@ -38,6 +38,7 @@ func Group(s *Server, path string) *Server {
 	if newServer.groupTag != "" {
 		s.OpenApiSpec.Tags = append(s.OpenApiSpec.Tags, &openapi3.Tag{Name: newServer.groupTag})
 	}
+	newServer.mainRouter = s
 
 	return newServer
 }
@@ -48,6 +49,8 @@ type Route[ResponseBody any, RequestBody any] struct {
 	Path      string       // URL path. Will be prefixed by the base path of the server and the group path if any
 	Handler   http.Handler // handler executed for this route
 	FullName  string       // namespace and name of the function to execute
+
+	mainRouter *Server // ref to the main router, used to register the route in the OpenAPI spec
 }
 
 // Capture all methods (GET, POST, PUT, PATCH, DELETE) and register a controller.
@@ -129,6 +132,7 @@ func Register[T, B any](s *Server, route Route[T, B], controller http.Handler, m
 	route.Operation.Summary = route.NameFromNamespace(camelToHuman)
 	route.Operation.Description = "controller: `" + route.FullName + "`\n\n---\n\n"
 	route.Operation.OperationID = route.Method + "_" + s.basePath + strings.ReplaceAll(strings.ReplaceAll(route.Path, "{", ":"), "}", "")
+	route.mainRouter = s
 
 	return route
 }

openapi.go

@@ -180,12 +180,15 @@ func RegisterOpenAPIOperation[T, B any](s *Server, method, path string) (*openap
 		}
 	}
 
+	// Response - globals
+	for _, openAPIGlobalResponse := range s.globalOpenAPIResponses {
+		addResponse(s, operation, openAPIGlobalResponse.Code, openAPIGlobalResponse.Description, openAPIGlobalResponse.ErrorType)
+	}
+
+	// Response - 200
 	responseSchema := schemaTagFromType(s, *new(T))
 	content := openapi3.NewContentWithSchemaRef(&responseSchema.SchemaRef, []string{"application/json", "application/xml"})
-	response := openapi3.NewResponse().
-		WithDescription("OK").
-		WithContent(content)
-
+	response := openapi3.NewResponse().WithDescription("OK").WithContent(content)
 	operation.AddResponse(200, response)
 
 	// Path parameters

openapi_operations.go

@@ -82,6 +82,36 @@ func (r Route[ResponseBody, RequestBody]) AddTags(tags ...string) Route[Response
 	return r
 }
 
+// AddError adds an error to the route.
+func (r Route[ResponseBody, RequestBody]) AddError(code int, description string, errorType ...any) Route[ResponseBody, RequestBody] {
+	addResponse(r.mainRouter, r.Operation, code, description, errorType...)
+	return r
+}
+
+func addResponse(s *Server, operation *openapi3.Operation, code int, description string, errorType ...any) {
+	var responseSchema schemaTag
+
+	if len(errorType) > 0 {
+		responseSchema = schemaTagFromType(s, errorType[0])
+	} else {
+		responseSchema = schemaTagFromType(s, HTTPError{})
+	}
+	content := openapi3.NewContentWithSchemaRef(&responseSchema.SchemaRef, []string{"application/json"})
+
+	response := openapi3.NewResponse().
+		WithDescription(description).
+		WithContent(content)
+
+	operation.AddResponse(code, response)
+}
+
+// openAPIError describes a response error in the OpenAPI spec.
+type openAPIError struct {
+	Code        int
+	Description string
+	ErrorType   any
+}
+
 // RemoveTags removes tags from the route.
 func (r Route[ResponseBody, RequestBody]) RemoveTags(tags ...string) Route[ResponseBody, RequestBody] {
 	for _, tag := range tags {