feat(api): add shared response envelope schema

Co-Authored-By: Virgil <virgil@lethean.io>

openapi.go

@@ -53,6 +53,20 @@ func (sb *SpecBuilder) Build(groups []RouteGroup) ([]byte, error) {
 	// Add component schemas for the response envelope.
 	spec["components"] = map[string]any{
 		"schemas": map[string]any{
+			"Response": map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"success": map[string]any{"type": "boolean"},
+					"data":    map[string]any{},
+					"error": map[string]any{
+						"$ref": "#/components/schemas/Error",
+					},
+					"meta": map[string]any{
+						"$ref": "#/components/schemas/Meta",
+					},
+				},
+				"required": []string{"success"},
+			},
 			"Error": map[string]any{
 				"type": "object",
 				"properties": map[string]any{

openapi_test.go

@@ -101,6 +101,10 @@ func TestSpecBuilder_Good_EmptyGroups(t *testing.T) {
 	}
 
 	components := spec["components"].(map[string]any)
+	schemas := components["schemas"].(map[string]any)
+	if _, ok := schemas["Response"]; !ok {
+		t.Fatal("expected Response component schema in spec")
+	}
 	securitySchemes := components["securitySchemes"].(map[string]any)
 	bearerAuth := securitySchemes["bearerAuth"].(map[string]any)
 	if bearerAuth["type"] != "http" {