Добавлен Swagger #20

src/handlers/admin/admin_handler_event_by_id.erl

@@ -2,16 +2,146 @@
 -behaviour(cowboy_handler).
 
 -export([init/2]).
+-export([trails/0]).
+
 -include("records.hrl").
 
+%%%===================================================================
+%%% cowboy_handler callback
+%%%===================================================================
+
 init(Req, _Opts) ->
   case cowboy_req:method(Req) of
-    <<"GET">> -> get_event(Req);
-    <<"PUT">> -> update_event(Req);
+    <<"GET">>    -> get_event(Req);
+    <<"PUT">>    -> update_event(Req);
     <<"DELETE">> -> delete_event(Req);
-    _ -> send_error(Req, 405, <<"Method not allowed">>)
+    _            -> send_error(Req, 405, <<"Method not allowed">>)
   end.
 
+%%%===================================================================
+%%% Swagger / Trails metadata
+%%%===================================================================
+
+trails() ->
+  Path = <<"/v1/admin/events/:id">>,
+  BaseParams = [
+    #{
+      name => <<"id">>,
+      in => <<"path">>,
+      description => <<"Event ID">>,
+      required => true,
+      schema => #{type => string}
+    }
+  ],
+  [
+    %% GET
+    #{
+      path => Path,
+      method => <<"GET">>,
+      handler => ?MODULE,
+      tags => [<<"Events: id">>],
+      description => <<"Get event by ID (admin)">>,
+      parameters => BaseParams,
+      responses => #{
+        200 => #{
+          description => <<"Event details">>,
+          content => #{
+            <<"application/json">> => #{
+              schema => event_schema()
+            }
+          }
+        }
+      }
+    },
+    %% PUT
+    #{
+      path => Path,
+      method => <<"PUT">>,
+      handler => ?MODULE,
+      tags => [<<"Events: id">>],
+      description => <<"Update event (admin)">>,
+      parameters => BaseParams,
+      requestBody => #{
+        required => true,
+        content => #{
+          <<"application/json">> => #{
+            schema => event_update_schema()
+          }
+        }
+      },
+      responses => #{
+        200 => #{description => <<"Updated event">>}
+      }
+    },
+    %% DELETE
+    #{
+      path => Path,
+      method => <<"DELETE">>,
+      handler => ?MODULE,
+      tags => [<<"Events: id">>],
+      description => <<"Soft-delete event (admin)">>,
+      parameters => BaseParams,
+      responses => #{
+        200 => #{description => <<"Event status set to deleted">>}
+      }
+    }
+  ].
+
+event_schema() ->
+  #{
+    type => object,
+    properties => #{
+      id => #{type => string},
+      calendar_id => #{type => string},
+      title => #{type => string},
+      description => #{type => string},
+      event_type => #{type => string, enum => [<<"single">>, <<"recurring">>]},
+      start_time => #{type => string, format => <<"date-time">>},
+      duration => #{type => integer},
+      recurrence => #{type => object, nullable => true},
+      master_id => #{type => string, nullable => true},
+      is_instance => #{type => boolean},
+      specialist_id => #{type => string, nullable => true},
+      location => #{type => object, nullable => true},
+      tags => #{type => array, items => #{type => string}},
+      capacity => #{type => integer, nullable => true},
+      online_link => #{type => string, nullable => true},
+      status => #{type => string, enum => [<<"active">>, <<"cancelled">>, <<"completed">>]},
+      rating_avg => #{type => number, format => float},
+      rating_count => #{type => integer},
+      created_at => #{type => string, format => <<"date-time">>},
+      updated_at => #{type => string, format => <<"date-time">>}
+    }
+  }.
+
+event_update_schema() ->
+  #{
+    type => object,
+    properties => #{
+      title => #{type => string},
+      description => #{type => string},
+      start_time => #{type => string, format => <<"date-time">>},
+      duration => #{type => integer},
+      status => #{type => string, enum => [<<"active">>, <<"cancelled">>, <<"completed">>]},
+      specialist_id => #{type => string},
+      location => #{
+        type => object,
+        properties => #{
+          address => #{type => string},
+          lat => #{type => number, format => float},
+          lon => #{type => number, format => float}
+        }
+      },
+      tags => #{type => array, items => #{type => string}},
+      capacity => #{type => integer},
+      online_link => #{type => string}
+    }
+  }.
+
+%%%===================================================================
+%%% Internal functions
+%%%===================================================================
+
 %% GET /v1/admin/events/:id
 get_event(Req) ->
   case auth_admin(Req) of
@@ -73,7 +203,9 @@ delete_event(Req) ->
       send_error(Req1, Code, Msg)
   end.
 
-%% --- Вспомогательные функции (идентичны handler_event_by_id.erl) ---
+%%--------------------------------------------------------------------
+%% Auth helpers
+%%--------------------------------------------------------------------
 
 auth_admin(Req) ->
   case handler_auth:authenticate(Req) of
@@ -86,6 +218,10 @@ auth_admin(Req) ->
       {error, Code, Msg, Req1}
   end.
 
+%%--------------------------------------------------------------------
+%% Field conversion (from binary keys/values to internal atoms)
+%%--------------------------------------------------------------------
+
 convert_fields(Updates) ->
   lists:map(fun convert_field/1, Updates).
 
@@ -117,10 +253,14 @@ convert_field({<<"status">>, Val}) ->
   try binary_to_existing_atom(Val, utf8) of
     Atom -> {status, Atom}
   catch
-    error:badarg -> {status, Val}   % fallback, но лучше залогировать
+    error:badarg -> {status, Val}
   end;
 convert_field(Other) -> Other.
 
+%%--------------------------------------------------------------------
+%% JSON / datetime helpers
+%%--------------------------------------------------------------------
+
 event_to_json(Event) ->
   LocationJson = case Event#event.location of
                    undefined -> null;
@@ -185,6 +325,10 @@ parse_datetime(Str) ->
   catch _:_ -> {error, invalid_format}
   end.
 
+%%--------------------------------------------------------------------
+%% Response helpers
+%%--------------------------------------------------------------------
+
 send_json(Req, Status, Data) ->
   Body = jsx:encode(Data),
   Headers = #{<<"content-type">> => <<"application/json">>},