EventHub/EventHubBack
1
1
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

Добавлен Swagger #20

Browse Source
This commit is contained in:
Алексей Сабилин
2026-05-09 18:15:45 +03:00
parent a34e36b966
commit a35d6f7acc
9 changed files with 419 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
Makefile
View File

@@ -263,6 +263,7 @@ docker-compose-up: ## Запустить кластер (3 ноды)
@echo "ObserverWeb: http://localhost:4000/observer/"
@echo "Traefik: http://localhost:8080"
@echo "LogLynx: http://localhost:6123"
@echo "Swagger UI: http://localhost:8447"
docker-compose-down: ## Остановить кластер
@echo "Остановка кластера..."

3
rebar.config
View File

@@ -9,7 +9,8 @@
{argon2, "1.2.0"},
{meck, "0.9.2"},
{gun, "2.2.0"},
{prometheus_cowboy, "0.2.0"}
{prometheus_cowboy, "0.2.0"},
{cowboy_swagger, "2.8.0"}
]}.
{shell, [

3
src/config/sys.config
View File

@@ -13,5 +13,8 @@
#{formatter => {logger_formatter, #{template => [time, " ", level, ": ", msg, "\n"]}}}
}
]}
]},
{ cowboy_swagger, [
{ static_files, "./_build/default/lib/cowboy_swagger/priv/swagger" }
]}
].

4
src/eventhub.app.src
View File

@@ -9,7 +9,9 @@
mnesia,
crypto,
cowboy,
jsx
jsx,
trails,
cowboy_swagger
]},
{env, [
{http_port, 8080},

17
src/eventhub_app.erl
View File

@@ -45,6 +45,7 @@ start(_StartType, _StartArgs) ->
calendar_html_renderer:init_cache(),
start_http(), % Пользовательский API (8080)
start_admin_http(), % Административный API (8445)
start_swagger_http(), % Swagger UI и спецификация (8447)
application:ensure_all_started(prometheus),
application:ensure_all_started(prometheus_cowboy),
init_default_admins(),
@@ -153,6 +154,22 @@ start_admin_http() ->
io:format("WebSocket started on ports ~p (user) and ~p (admin)~n", [PortWs, PortAdminWs]).
%% ===================================================================
%% Swagger HTTP (порт 8447) — документация API
%% ===================================================================
start_swagger_http() ->
PortSwagger = get_env_int(swagger_http_port, 8447),
Dispatch = cowboy_router:compile([
{'_', [
{"/", swagger_docs_handler, []},
{"/[...]", swagger_docs_handler, []}
]}
]),
Middlewares = [cowboy_router, cowboy_handler],
Env = #{dispatch => Dispatch},
cowboy:start_clear(swagger_http, [{port, PortSwagger}], #{env => Env, middlewares => Middlewares}),
io:format("Swagger HTTP server started on port ~p~n", [PortSwagger]).
%% ---------- Инициализация администраторов ----------
init_default_admins() ->
case core_admin:list_all() of

148
src/handlers/admin/admin_handler_event_by_id.erl
View File

@@ -2,8 +2,14 @@
-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);
@@ -12,6 +18,130 @@ init(Req, _Opts) ->
_ -> 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">>},

121
src/handlers/admin/admin_handler_events.erl
View File

@@ -2,14 +2,92 @@
-behaviour(cowboy_handler).
-export([init/2]).
-export([trails/0]).
-include("records.hrl").
%%%===================================================================
%%% cowboy_handler callbacks
%%%===================================================================
init(Req, _Opts) ->
case cowboy_req:method(Req) of
<<"GET">> -> list_all_events(Req);
_ -> send_error(Req, 405, <<"Method not allowed">>)
end.
%%%===================================================================
%%% Swagger / Trails metadata
%%%===================================================================
trails() ->
[
#{
path => <<"/v1/admin/events">>,
method => <<"GET">>,
handler => ?MODULE,
tags => [<<"Events">>],
description => <<"Search and list events (admin)">>,
parameters => [
#{name => <<"from">>, in => <<"query">>, description => <<"ISO8601 start datetime">>, required => false, schema => #{type => string}},
#{name => <<"to">>, in => <<"query">>, description => <<"ISO8601 end datetime">>, required => false, schema => #{type => string}},
#{name => <<"status">>, in => <<"query">>, description => <<"active, cancelled, completed, or all">>, required => false, schema => #{type => string}},
#{name => <<"calendar_id">>, in => <<"query">>, description => <<"Filter by calendar ID">>, required => false, schema => #{type => string}},
#{name => <<"title">>, in => <<"query">>, description => <<"Exact title match">>, required => false, schema => #{type => string}},
#{name => <<"q">>, in => <<"query">>, description => <<"Substring search in title/description">>, required => false, schema => #{type => string}},
#{name => <<"limit">>, in => <<"query">>, description => <<"Page size (max 200)">>, required => false, schema => #{type => integer}},
#{name => <<"offset">>, in => <<"query">>, description => <<"Offset">>, required => false, schema => #{type => integer}},
#{name => <<"sort">>, in => <<"query">>, description => <<"created_at, start_time, title, status">>, required => false, schema => #{type => string}},
#{name => <<"order">>, in => <<"query">>, description => <<"asc or desc">>, required => false, schema => #{type => string, enum => [<<"asc">>, <<"desc">>]}}
],
responses => #{
200 => #{
description => <<"Array of events with Content-Range header">>,
content => #{
<<"application/json">> => #{
schema => #{
type => array,
items => event_schema()
}
}
}
},
405 => #{description => <<"Method not allowed">>}
}
}
].
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">>}
}
}.
%%%===================================================================
%%% Internal functions
%%%===================================================================
list_all_events(Req) ->
case auth_admin(Req) of
{ok, _AdminId, Req1} ->
@@ -26,9 +104,7 @@ list_all_events(Req) ->
<<"x-total-count">> => integer_to_binary(Total),
<<"access-control-expose-headers">> => <<"Content-Range, X-Total-Count">>
},
Body = jsx:encode(Json),
cowboy_req:reply(200, Headers, Body, Req1),
{ok, Body, []};
send_json(Req1, 200, Json, Headers);
{error, Code, Msg, Req1} ->
send_error(Req1, Code, Msg)
end.
@@ -48,9 +124,6 @@ parse_admin_event_search(Req) ->
order => proplists:get_value(<<"order">>, Qs, <<"desc">>)
}.
%%--------------------------------------------------------------------
%% Вспомогательные функции
%%--------------------------------------------------------------------
auth_admin(Req) ->
case handler_auth:authenticate(Req) of
{ok, AdminId, Req1} ->
@@ -70,6 +143,22 @@ parse_datetime_qs(undefined) -> undefined;
parse_datetime_qs(Bin) ->
case parse_datetime(Bin) of {ok, Dt} -> Dt; _ -> undefined end.
parse_datetime(Str) ->
try
[DateStr, TimeStr] = string:split(Str, "T"),
TimeStrNoZ = string:trim(TimeStr, trailing, "Z"),
[YearStr, MonthStr, DayStr] = string:split(DateStr, "-", all),
[HourStr, MinuteStr, SecondStr] = string:split(TimeStrNoZ, ":", all),
Year = binary_to_integer(list_to_binary(YearStr)),
Month = binary_to_integer(list_to_binary(MonthStr)),
Day = binary_to_integer(list_to_binary(DayStr)),
Hour = binary_to_integer(list_to_binary(HourStr)),
Minute = binary_to_integer(list_to_binary(MinuteStr)),
Second = binary_to_integer(list_to_binary(SecondStr)),
{ok, {{Year, Month, Day}, {Hour, Minute, Second}}}
catch _:_ -> {error, invalid_format}
end.
event_to_json(Event) ->
LocationJson = case Event#event.location of
undefined -> null;
@@ -118,21 +207,11 @@ datetime_to_iso8601({{Year, Month, Day}, {Hour, Minute, Second}}) ->
datetime_to_iso8601(undefined) ->
undefined.
parse_datetime(Str) ->
try
[DateStr, TimeStr] = string:split(Str, "T"),
TimeStrNoZ = string:trim(TimeStr, trailing, "Z"),
[YearStr, MonthStr, DayStr] = string:split(DateStr, "-", all),
[HourStr, MinuteStr, SecondStr] = string:split(TimeStrNoZ, ":", all),
Year = binary_to_integer(list_to_binary(YearStr)),
Month = binary_to_integer(list_to_binary(MonthStr)),
Day = binary_to_integer(list_to_binary(DayStr)),
Hour = binary_to_integer(list_to_binary(HourStr)),
Minute = binary_to_integer(list_to_binary(MinuteStr)),
Second = binary_to_integer(list_to_binary(SecondStr)),
{ok, {{Year, Month, Day}, {Hour, Minute, Second}}}
catch _:_ -> {error, invalid_format}
end.
send_json(Req, Status, Data, ExtraHeaders) ->
Body = jsx:encode(Data),
Headers = maps:merge(#{<<"content-type">> => <<"application/json">>}, ExtraHeaders),
cowboy_req:reply(Status, Headers, Body, Req),
{ok, Body, []}.
send_error(Req, Status, Message) ->
Body = jsx:encode(#{error => Message}),

96
src/handlers/swagger_docs_handler.erl Normal file
View File

@@ -0,0 +1,96 @@
-module(swagger_docs_handler).
-behaviour(cowboy_handler).
-export([init/2]).
init(Req, _Opts) ->
Path = cowboy_req:path(Req),
handle(Path, Req).
handle(<<"/">>, Req) ->
serve_index(Req);
handle(<<"/admin">>, Req) ->
redirect_to_slash(<<"/admin/">>, Req);
handle(<<"/admin/">>, Req) ->
serve_ui(admin, Req);
handle(<<"/admin/swagger.json">>, Req) ->
serve_json(admin, Req);
handle(<<"/client">>, Req) ->
redirect_to_slash(<<"/client/">>, Req);
handle(<<"/client/">>, Req) ->
serve_ui(client, Req);
handle(<<"/client/swagger.json">>, Req) ->
serve_json(client, Req);
handle(_, Req) ->
cowboy_req:reply(404, #{}, <<"Not Found">>, Req),
{ok, [], []}.
%% Главная страница с выбором API
serve_index(Req) ->
Html = <<"<!DOCTYPE html>
<html>
<head><title>EventHub API Docs</title></head>
<body>
<h1>EventHub API Documentation</h1>
<ul>
<li><a href=\"/admin/\">Admin API</a></li>
<li><a href=\"/client/\">Client API</a></li>
</ul>
</body>
</html>">>,
cowboy_req:reply(200, #{<<"content-type">> => <<"text/html">>}, Html, Req),
{ok, Html, []}.
%% Swagger UI для конкретного API
serve_ui(Api, Req) ->
{Title, SpecUrl} = case Api of
admin -> {<<"EventHub Admin API">>, <<"/admin/swagger.json">>};
client -> {<<"EventHub Client API">>, <<"/client/swagger.json">>}
end,
Html = iolist_to_binary([
"<!DOCTYPE html><html><head><title>", Title,
"</title><link rel=\"stylesheet\" href=\"https://unpkg.com/swagger-ui-dist@5/swagger-ui.css\">",
"</head><body><div id=\"swagger-ui\"></div>",
"<script src=\"https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js\"></script>",
"<script>window.onload=function(){SwaggerUIBundle({url:'", SpecUrl,
"',dom_id:'#swagger-ui',presets:[SwaggerUIBundle.presets.apis,SwaggerUIBundle.SwaggerUIStandalonePreset],layout:'BaseLayout'});}</script>",
"</body></html>"
]),
cowboy_req:reply(200, #{<<"content-type">> => <<"text/html">>}, Html, Req),
{ok, Html, []}.
%% Генерация OpenAPI JSON
serve_json(Api, Req) ->
Trails = case Api of
admin -> trails:admin();
client -> trails:client()
end,
OpenApi = #{
openapi => <<"3.0.3">>,
info => #{
title => case Api of
admin -> <<"EventHub Admin API">>;
client -> <<"EventHub Client API">>
end,
version => <<"1.0.0">>
},
servers => [#{url => <<"http://localhost:8445">>, description => <<"API server">>}],
paths => build_paths(Trails)
},
Json = jsx:encode(OpenApi),
cowboy_req:reply(200, #{<<"content-type">> => <<"application/json">>}, Json, Req),
{ok, Json, []}.
build_paths(Trails) ->
lists:foldl(fun(Trail, Acc) ->
Path = maps:get(path, Trail, <<"/">>),
Method0 = maps:get(method, Trail, <<"get">>),
Method = string:lowercase(Method0),
TrailData = maps:without([path, method], Trail),
PathItem = #{Method => TrailData},
maps:merge_with(fun(_, V1, V2) -> maps:merge(V1, V2) end, Acc, #{Path => PathItem})
end, #{}, Trails).
redirect_to_slash(Location, Req) ->
cowboy_req:reply(301, #{<<"location">> => Location}, <<>>, Req),
{ok, [], []}.

25
src/swagger/trails.erl Normal file
View File

@@ -0,0 +1,25 @@
-module(trails).
-export([admin/0, client/0, all/0]).
admin() ->
Modules = [
admin_handler_events,
admin_handler_event_by_id
%% другие админские обработчики с trails/0
],
lists:flatmap(fun trails_from_module/1, Modules).
client() ->
Modules = [
%% пока пусто; добавьте handler_events, handler_event_by_id и др.
],
lists:flatmap(fun trails_from_module/1, Modules).
all() ->
admin() ++ client().
trails_from_module(Module) ->
try Module:trails() of
Trails when is_list(Trails) -> Trails
catch error:undef -> []
end.