fix: update openapi spec for other apis

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,

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,
+        required: false
-        example: "00000000-0000-0000-0000-000000000000"
       ],
       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,
+        required: false
-        example: "map-name"
       ]
     ],
     responses: [
-      ok: {
+      ok: {"List of ACLs", "application/json", @acl_index_response_schema},
-        "List of ACLs",
-        "application/json",
-        @acl_index_response_schema
-      },
       bad_request: {"Error", "application/json", %OpenApiSpex.Schema{
         type: :object,
-        properties: %{
+        properties: %{error: %OpenApiSpex.Schema{type: :string}},
-          error: %OpenApiSpex.Schema{type: :string}
-        },
         required: ["error"],
-        example: %{
+        example: %{"error" => "Must provide only one of map_id or slug as a query parameter"}
-          "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."
-        }
       }}
     ]
   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",
+    summary: "Create ACL for a Map",
-    description: "Creates a new ACL for a map. Requires either 'map_id' or 'slug' as a query parameter to identify the 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,
+        required: false
-        example: "00000000-0000-0000-0000-000000000000"
       ],
       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,
+        required: false
-        example: "map-name"
       ]
     ],
-    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: %{
+        properties: %{error: %OpenApiSpex.Schema{type: :string}},
-          error: %OpenApiSpex.Schema{type: :string}
-        },
         required: ["error"],
-        example: %{
+        example: %{"error" => "Must provide only one of map_id or slug as a query parameter"}
-          "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."
-        }
       }}
     ]
   def create(conn, params) do

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,
+        required: false
-        example: ""
       ],
       slug: [
         in: :query,
         description: "Map slug - Either map_id or slug must be provided",
         type: :string,
-        required: false,
+        required: false
-        example: "map-name"
       ]
     ],
     responses: [

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_source: [
-      solar_system_target: [in: :query, type: :integer, required: false]
+        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]],
+    parameters: [
-    responses: ResponseSchemas.standard_responses(@list_response_schema)
+      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)

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
 

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."
+  Get structure timers for a map.
-  Legacy: Get structure timers for a map.
   """
   operation :structure_timers,
-    summary: "Get structure timers for a map (Legacy)",
+    summary: "Get structure timers for a map",
-    deprecated: true,
     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)

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