diff --git a/lib/wanderer_app/map/server/map_server_signatures_impl.ex b/lib/wanderer_app/map/server/map_server_signatures_impl.ex index d9cea2c2..7792e5e1 100644 --- a/lib/wanderer_app/map/server/map_server_signatures_impl.ex +++ b/lib/wanderer_app/map/server/map_server_signatures_impl.ex @@ -12,7 +12,7 @@ defmodule WandererApp.Map.Server.SignaturesImpl do Public entrypoint for updating signatures on a map system. """ def update_signatures( - state = %{map_id: map_id}, + %{map_id: map_id} = state, %{ solar_system_id: system_solar_id, character_id: char_id, diff --git a/lib/wanderer_app_web/controllers/access_list_api_controller.ex b/lib/wanderer_app_web/controllers/access_list_api_controller.ex index c1104230..df86737b 100644 --- a/lib/wanderer_app_web/controllers/access_list_api_controller.ex +++ b/lib/wanderer_app_web/controllers/access_list_api_controller.ex @@ -200,48 +200,28 @@ defmodule WandererAppWeb.MapAccessListAPIController do @spec index(Plug.Conn.t(), map()) :: Plug.Conn.t() operation :index, summary: "List ACLs for a Map", - description: "Lists the ACLs for a given map. Requires either 'map_id' or 'slug' as a query parameter to identify the map.", + description: "Lists the ACLs for a given map. Provide only one of map_id or slug as a query parameter. If both are provided, the request will fail.", parameters: [ map_id: [ in: :query, - description: "Map identifier (UUID) - Either map_id or slug must be provided", + description: "Map identifier (UUID) - Provide only one of map_id or slug.", type: :string, - required: false, - example: "00000000-0000-0000-0000-000000000000" + required: false ], slug: [ in: :query, - description: "Map slug - Either map_id or slug must be provided", + description: "Map slug - Provide only one of map_id or slug.", type: :string, - required: false, - example: "map-name" + required: false ] ], responses: [ - ok: { - "List of ACLs", - "application/json", - @acl_index_response_schema - }, + ok: {"List of ACLs", "application/json", @acl_index_response_schema}, bad_request: {"Error", "application/json", %OpenApiSpex.Schema{ type: :object, - properties: %{ - error: %OpenApiSpex.Schema{type: :string} - }, + properties: %{error: %OpenApiSpex.Schema{type: :string}}, required: ["error"], - example: %{ - "error" => "Must provide either ?map_id=UUID or ?slug=SLUG as a query parameter" - } - }}, - not_found: {"Error", "application/json", %OpenApiSpex.Schema{ - type: :object, - properties: %{ - error: %OpenApiSpex.Schema{type: :string} - }, - required: ["error"], - example: %{ - "error" => "Map not found. Please provide a valid map_id or slug as a query parameter." - } + example: %{"error" => "Must provide only one of map_id or slug as a query parameter"} }} ] def index(conn, params) do @@ -277,46 +257,30 @@ defmodule WandererAppWeb.MapAccessListAPIController do """ @spec create(Plug.Conn.t(), map()) :: Plug.Conn.t() operation :create, - summary: "Create a new ACL", - description: "Creates a new ACL for a map. Requires either 'map_id' or 'slug' as a query parameter to identify the map.", + summary: "Create ACL for a Map", + description: "Creates a new ACL for a given map. Provide only one of map_id or slug as a query parameter. If both are provided, the request will fail.", parameters: [ map_id: [ in: :query, - description: "Map identifier (UUID) - Either map_id or slug must be provided", + description: "Map identifier (UUID) - Provide only one of map_id or slug.", type: :string, - required: false, - example: "00000000-0000-0000-0000-000000000000" + required: false ], slug: [ in: :query, - description: "Map slug - Either map_id or slug must be provided", + description: "Map slug - Provide only one of map_id or slug.", type: :string, - required: false, - example: "map-name" + required: false ] ], - request_body: {"Access List parameters", "application/json", @acl_create_request_schema}, + request_body: {"ACL parameters", "application/json", @acl_create_request_schema}, responses: [ - ok: {"Access List", "application/json", @acl_create_response_schema}, + created: {"Created ACL", "application/json", @acl_create_response_schema}, bad_request: {"Error", "application/json", %OpenApiSpex.Schema{ type: :object, - properties: %{ - error: %OpenApiSpex.Schema{type: :string} - }, + properties: %{error: %OpenApiSpex.Schema{type: :string}}, required: ["error"], - example: %{ - "error" => "Must provide either ?map_id=UUID or ?slug=SLUG as a query parameter" - } - }}, - not_found: {"Error", "application/json", %OpenApiSpex.Schema{ - type: :object, - properties: %{ - error: %OpenApiSpex.Schema{type: :string} - }, - required: ["error"], - example: %{ - "error" => "Map not found. Please provide a valid map_id or slug as a query parameter." - } + example: %{"error" => "Must provide only one of map_id or slug as a query parameter"} }} ] def create(conn, params) do diff --git a/lib/wanderer_app_web/controllers/map_api_controller.ex b/lib/wanderer_app_web/controllers/map_api_controller.ex index be2d110e..ba8b1f30 100644 --- a/lib/wanderer_app_web/controllers/map_api_controller.ex +++ b/lib/wanderer_app_web/controllers/map_api_controller.ex @@ -246,7 +246,6 @@ defmodule WandererAppWeb.MapAPIController do in: :query, description: "Map slug", type: :string, - example: "my-map", required: false ], map_id: [ @@ -319,7 +318,7 @@ defmodule WandererAppWeb.MapAPIController do end @doc """ - GET /api/map/structure_timers + GET /api/map/structure-timers Returns structure timers for visible systems on the map or for a specific system. """ @@ -327,6 +326,7 @@ defmodule WandererAppWeb.MapAPIController do operation :show_structure_timers, summary: "Show Structure Timers", description: "Retrieves structure timers for a map.", + deprecated: true, parameters: [ map_id: [ in: :query, @@ -342,7 +342,7 @@ defmodule WandererAppWeb.MapAPIController do ], system_id: [ in: :query, - description: "System ID", + description: "Optional: System ID to filter timers for a specific system", type: :string, required: false ] @@ -790,15 +790,13 @@ defmodule WandererAppWeb.MapAPIController do in: :query, description: "Map identifier (UUID) - Either map_id or slug must be provided", type: :string, - required: false, - example: "" + required: false ], slug: [ in: :query, description: "Map slug - Either map_id or slug must be provided", type: :string, - required: false, - example: "map-name" + required: false ] ], responses: [ diff --git a/lib/wanderer_app_web/controllers/map_connection_api_controller.ex b/lib/wanderer_app_web/controllers/map_connection_api_controller.ex index 2c9c162a..c9f73f78 100644 --- a/lib/wanderer_app_web/controllers/map_connection_api_controller.ex +++ b/lib/wanderer_app_web/controllers/map_connection_api_controller.ex @@ -129,23 +129,46 @@ defmodule WandererAppWeb.MapConnectionAPIController do operation :index, summary: "List Map Connections", + description: "Lists all connections for a map.", parameters: [ map_identifier: [ in: :path, - description: "Map identifier (UUID or slug). Provide either a UUID or a slug.", + description: "Map identifier (UUID or slug)", type: :string, required: true, example: "map-slug or map UUID" ], - solar_system_source: [in: :query, type: :integer, required: false], - solar_system_target: [in: :query, type: :integer, required: false] + solar_system_source: [ + in: :query, + description: "Filter connections by source system ID", + type: :integer, + required: false, + example: 30000142 + ], + solar_system_target: [ + in: :query, + description: "Filter connections by target system ID", + type: :integer, + required: false, + example: 30000144 + ] ], responses: [ ok: { - "List Map Connections", + "List of Map Connections", "application/json", @list_response_schema - } + }, + not_found: {"Error", "application/json", %OpenApiSpex.Schema{ + type: :object, + properties: %{ + error: %OpenApiSpex.Schema{type: :string} + }, + required: ["error"], + example: %{ + "error" => "Map not found" + } + }} ] def index(%{assigns: %{map_id: map_id}} = conn, params) do with {:ok, src_filter} <- parse_optional(params, "solar_system_source"), @@ -187,7 +210,7 @@ defmodule WandererAppWeb.MapConnectionAPIController do parameters: [ map_identifier: [ in: :path, - description: "Map identifier (UUID or slug). Provide either a UUID or a slug.", + description: "Map identifier (UUID or slug)", type: :string, required: true, example: "map-slug or map UUID" @@ -218,12 +241,11 @@ defmodule WandererAppWeb.MapConnectionAPIController do parameters: [ map_identifier: [ in: :path, - description: "Map identifier (UUID or slug). Provide either a UUID or a slug.", + description: "Map identifier (UUID or slug)", type: :string, required: true, example: "map-slug or map UUID" - ], - system_id: [in: :path, type: :string, required: false] + ] ], request_body: {"Connection create", "application/json", @connection_request_schema}, responses: ResponseSchemas.create_responses(@detail_response_schema) @@ -256,7 +278,7 @@ defmodule WandererAppWeb.MapConnectionAPIController do parameters: [ map_identifier: [ in: :path, - description: "Map identifier (UUID or slug). Provide either a UUID or a slug.", + description: "Map identifier (UUID or slug)", type: :string, required: true, example: "map-slug or map UUID" @@ -344,7 +366,7 @@ defmodule WandererAppWeb.MapConnectionAPIController do parameters: [ map_identifier: [ in: :path, - description: "Map identifier (UUID or slug). Provide either a UUID or a slug.", + description: "Map identifier (UUID or slug)", type: :string, required: true, example: "map-slug or map UUID" @@ -442,9 +464,49 @@ defmodule WandererAppWeb.MapConnectionAPIController do @deprecated "Use GET /api/maps/:map_identifier/systems instead" operation :list_all_connections, summary: "List All Connections (Legacy)", + description: "Legacy endpoint for listing connections. Use GET /api/maps/:map_identifier/connections instead. Requires exactly one of map_id or slug as a query parameter. If both are provided, a 400 Bad Request will be returned.", deprecated: true, - parameters: [map_id: [in: :query]], - responses: ResponseSchemas.standard_responses(@list_response_schema) + parameters: [ + map_id: [ + in: :query, + description: "Map identifier (UUID) - Exactly one of map_id or slug must be provided", + type: :string, + required: false + ], + slug: [ + in: :query, + description: "Map slug - Exactly one of map_id or slug must be provided", + type: :string, + required: false + ] + ], + responses: [ + ok: { + "List of Map Connections", + "application/json", + @list_response_schema + }, + bad_request: {"Error", "application/json", %OpenApiSpex.Schema{ + type: :object, + properties: %{ + error: %OpenApiSpex.Schema{type: :string} + }, + required: ["error"], + example: %{ + "error" => "Must provide exactly one of map_id or slug as a query parameter" + } + }}, + not_found: {"Error", "application/json", %OpenApiSpex.Schema{ + type: :object, + properties: %{ + error: %OpenApiSpex.Schema{type: :string} + }, + required: ["error"], + example: %{ + "error" => "Map not found. Please provide a valid map_id or slug as a query parameter." + } + }} + ] def list_all_connections(%{assigns: %{map_id: map_id}} = conn, _params) do connections = Operations.list_connections(map_id) data = Enum.map(connections, &APIUtils.connection_to_json/1) diff --git a/lib/wanderer_app_web/controllers/map_system_api_controller.ex b/lib/wanderer_app_web/controllers/map_system_api_controller.ex index 6cc91911..29f45da9 100644 --- a/lib/wanderer_app_web/controllers/map_system_api_controller.ex +++ b/lib/wanderer_app_web/controllers/map_system_api_controller.ex @@ -290,10 +290,10 @@ defmodule WandererAppWeb.MapSystemAPIController do parameters: [ map_identifier: [ in: :path, - description: "Map identifier (UUID or slug). Provide either a UUID or a slug.", + description: "Map identifier (UUID or slug)", type: :string, required: true, - example: "my-map-slug or map UUID" + example: "map-slug or map UUID" ] ], responses: [ @@ -314,12 +314,17 @@ defmodule WandererAppWeb.MapSystemAPIController do parameters: [ map_identifier: [ in: :path, - description: "Map identifier (UUID or slug). Provide either a UUID or a slug.", + description: "Map identifier (UUID or slug)", type: :string, required: true, - example: "my-map-slug or map UUID" + example: "map-slug or map UUID" ], - id: [in: :path, type: :string, required: true] + id: [ + in: :path, + description: "System ID", + type: :string, + required: true + ] ], responses: ResponseSchemas.standard_responses(@detail_response_schema) def show(%{assigns: %{map_id: map_id}} = conn, %{"id" => id}) do @@ -334,10 +339,10 @@ defmodule WandererAppWeb.MapSystemAPIController do parameters: [ map_identifier: [ in: :path, - description: "Map identifier (UUID or slug). Provide either a UUID or a slug.", + description: "Map identifier (UUID or slug)", type: :string, required: true, - example: "my-map-slug or map UUID" + example: "map-slug or map UUID" ] ], request_body: {"Systems+Connections upsert", "application/json", @batch_request_schema}, @@ -358,12 +363,17 @@ defmodule WandererAppWeb.MapSystemAPIController do parameters: [ map_identifier: [ in: :path, - description: "Map identifier (UUID or slug). Provide either a UUID or a slug.", + description: "Map identifier (UUID or slug)", type: :string, required: true, - example: "my-map-slug or map UUID" + example: "map-slug or map UUID" ], - id: [in: :path, type: :string, required: true] + id: [ + in: :path, + description: "System ID", + type: :string, + required: true + ] ], request_body: {"System update request", "application/json", @system_update_schema}, responses: ResponseSchemas.update_responses(@detail_response_schema) @@ -381,10 +391,10 @@ defmodule WandererAppWeb.MapSystemAPIController do parameters: [ map_identifier: [ in: :path, - description: "Map identifier (UUID or slug). Provide either a UUID or a slug.", + description: "Map identifier (UUID or slug)", type: :string, required: true, - example: "my-map-slug or map UUID" + example: "map-slug or map UUID" ] ], request_body: {"Batch delete", "application/json", @batch_delete_schema}, @@ -428,12 +438,17 @@ defmodule WandererAppWeb.MapSystemAPIController do parameters: [ map_identifier: [ in: :path, - description: "Map identifier (UUID or slug). Provide either a UUID or a slug.", + description: "Map identifier (UUID or slug)", type: :string, required: true, - example: "my-map-slug or map UUID" + example: "map-slug or map UUID" ], - id: [in: :path, type: :string, required: true] + id: [ + in: :path, + description: "System ID", + type: :string, + required: true + ] ], responses: ResponseSchemas.standard_responses(@delete_response_schema) def delete_single(conn, %{"id" => id}) do @@ -462,7 +477,20 @@ defmodule WandererAppWeb.MapSystemAPIController do summary: "List Map Systems (Legacy)", deprecated: true, description: "Deprecated, use GET /api/maps/:map_identifier/systems instead", - parameters: [map_id: [in: :query]], + parameters: [ + map_id: [ + in: :query, + description: "Map identifier (UUID) - Either map_id or slug must be provided, but not both", + type: :string, + required: false, + ], + slug: [ + in: :query, + description: "Map slug - Either map_id or slug must be provided, but not both", + type: :string, + required: false, + ] + ], responses: ResponseSchemas.standard_responses(@list_response_schema) defdelegate list_systems(conn, params), to: __MODULE__, as: :index @@ -470,7 +498,26 @@ defmodule WandererAppWeb.MapSystemAPIController do summary: "Show Map System (Legacy)", deprecated: true, description: "Deprecated, use GET /api/maps/:map_identifier/systems/:id instead", - parameters: [map_id: [in: :query], id: [in: :query]], + parameters: [ + map_id: [ + in: :query, + description: "Map identifier (UUID) - Either map_id or slug must be provided, but not both", + type: :string, + required: false, + ], + slug: [ + in: :query, + description: "Map slug - Either map_id or slug must be provided, but not both", + type: :string, + required: false, + ], + id: [ + in: :query, + description: "System ID", + type: :string, + required: true + ] + ], responses: ResponseSchemas.standard_responses(@detail_response_schema) defdelegate show_system(conn, params), to: __MODULE__, as: :show diff --git a/lib/wanderer_app_web/controllers/map_system_structure_api_controller.ex b/lib/wanderer_app_web/controllers/map_system_structure_api_controller.ex index 857b8434..c45d8681 100644 --- a/lib/wanderer_app_web/controllers/map_system_structure_api_controller.ex +++ b/lib/wanderer_app_web/controllers/map_system_structure_api_controller.ex @@ -8,7 +8,6 @@ defmodule WandererAppWeb.MapSystemStructureAPIController do @moduledoc """ API controller for managing map system structures. - Includes legacy structure-timers endpoint (deprecated). """ # Inlined OpenAPI schema for a map system structure @@ -174,16 +173,25 @@ defmodule WandererAppWeb.MapSystemStructureAPIController do end @doc """ - @deprecated "Use /structures instead. This endpoint will be removed in a future release." - Legacy: Get structure timers for a map. + Get structure timers for a map. """ operation :structure_timers, - summary: "Get structure timers for a map (Legacy)", - deprecated: true, + summary: "Get structure timers for a map", parameters: [ map_identifier: [in: :path, description: "Map identifier (UUID or slug)", type: :string, required: true] ], - responses: [ok: {"Structure timers", "application/json", %Schema{type: :array, items: %Schema{type: :object}}}] + responses: [ok: {"Structure timers", "application/json", %Schema{ + type: :object, + properties: %{ + data: %Schema{ + type: :array, + items: @structure_schema + } + }, + example: %{ + data: [@structure_schema.example] + } + }}] def structure_timers(conn, _params) do map_id = conn.assigns.map_id structures = MapOperations.list_structures(map_id) diff --git a/lib/wanderer_app_web/router.ex b/lib/wanderer_app_web/router.ex index 276dfbca..a3338df8 100644 --- a/lib/wanderer_app_web/router.ex +++ b/lib/wanderer_app_web/router.ex @@ -212,7 +212,7 @@ defmodule WandererAppWeb.Router do get "/system", MapSystemAPIController, :show_system get "/connections", MapConnectionAPIController, :list_all_connections get "/characters", MapAPIController, :list_tracked_characters - get "/structure-timers", MapSystemStructureAPIController, :structure_timers + get "/structure-timers", MapAPIController, :show_structure_timers get "/character-activity", MapAPIController, :character_activity get "/user_characters", MapAPIController, :user_characters