Rework health-check endpoint, spec, and tests (#2292)

### Summary

This pull request refactors the `/status/alive` healthcheck endpoint to
improve its reliability, documentation, and testing.

The previous implementation was handled directly by a plug, causing it
to be missing from the OpenAPI specification. Its associated tests were
also outdated and did not correctly test the plug's database
interaction.

### Changes

1.  **API Specification (`ApiSpec`):**
* Manually added the OpenAPI specification for the `GET /status/alive`
path. This ensures the healthcheck endpoint is correctly documented for
all API consumers.
    * Removed previous implementation `HealthcheckController`

### Swagger UI
<img width="1696" height="1047" alt="Screenshot 2025-08-19 at 4 54
51 PM"
src="https://github.com/user-attachments/assets/0638394c-6f4b-44b3-bbad-5cb9fb6ba55f"
/>

---------

Co-authored-by: Taras Tyshko <[email protected]>

Author: taras-tyshko

lib/nerves_hub_web/api_spec.ex

@@ -13,6 +13,7 @@ defmodule NervesHubWeb.ApiSpec do
   alias NervesHubWeb.API.OpenAPI.DeviceControllerSpecs
   alias NervesHubWeb.Endpoint
   alias NervesHubWeb.Router
+  alias NervesHubWeb.Plugs.ImAlive
 
   @behaviour OpenApi
 
@@ -28,7 +29,7 @@ defmodule NervesHubWeb.ApiSpec do
         version: "2.0.0"
       },
       # Populate the paths from a phoenix router
-      paths: Paths.from_router(Router),
+      paths: set_paths(),
       components: %Components{
         securitySchemes: %{
           "bearer_auth" => %SecurityScheme{
@@ -91,6 +92,10 @@ defmodule NervesHubWeb.ApiSpec do
           name: "Signing Keys",
           description: "Organization Signing Key management"
         },
+        %Tag{
+          name: "Status",
+          description: "Application healthcheck"
+        },
         %Tag{
           name: "Support Scripts",
           description: "Organization Support Script management"
@@ -101,4 +106,10 @@ defmodule NervesHubWeb.ApiSpec do
     # Discover request/response schemas from path specs
     |> OpenApiSpex.resolve_schema_modules()
   end
+
+  defp set_paths() do
+    Router
+    |> Paths.from_router()
+    |> Map.merge(ImAlive.status_path_spec())
+  end
 end

lib/nerves_hub_web/controllers/healthcheck_controller.ex

@@ -6,9 +6,10 @@ defmodule NervesHubWeb.Plugs.ImAlive do
 
   import Plug.Conn
 
+  @status_path "/status/alive"
   def init(config), do: config
 
-  def call(%{request_path: "/status/alive"} = conn, _) do
+  def call(%{request_path: @status_path} = conn, _) do
     case Ecto.Adapters.SQL.query(NervesHub.Repo, "SELECT true", []) do
       {:ok, _} -> send_result(conn, 200, "Hello, Friend!")
       _result -> send_result(conn, 500, "Sorry, Friend :(")
@@ -17,6 +18,40 @@ defmodule NervesHubWeb.Plugs.ImAlive do
 
   def call(conn, _), do: conn
 
+  def status_path_spec() do
+    %{
+      @status_path => %OpenApiSpex.PathItem{
+        get: %OpenApiSpex.Operation{
+          summary: "Check application status",
+          description:
+            "Provides a simple health check to verify that the application is running, responsive, and can connect to the database.",
+          tags: ["Status"],
+          operationId: "Status.alive",
+          responses: %{
+            "200" => %OpenApiSpex.Response{
+              description: "The application is running and the database is reachable.",
+              content: %{
+                "text/plain" => %OpenApiSpex.MediaType{
+                  schema: %OpenApiSpex.Schema{type: :string, example: "Hello, Friend!"}
+                }
+              }
+            },
+            "500" => %OpenApiSpex.Response{
+              description: "The application is running but the database is unreachable.",
+              content: %{
+                "text/plain" => %OpenApiSpex.MediaType{
+                  schema: %OpenApiSpex.Schema{type: :string, example: "Sorry, Friend :("}
+                }
+              }
+            }
+          },
+          # This endpoint does not require authentication, so we override the global security
+          security: []
+        }
+      }
+    }
+  end
+
   defp send_result(conn, code, message) do
     conn
     |> put_resp_content_type("text/plain")

lib/nerves_hub_web/plugs/im_alive.ex

@@ -79,11 +79,6 @@ defmodule NervesHubWeb.Router do
     plug(NervesHubWeb.API.Plugs.Device)
   end
 
-  scope "/" do
-    pipe_through(:api)
-    get("/healthcheck", NervesHubWeb.HealthcheckController, :index)
-  end
-
   scope "/api" do
     pipe_through(:api)
     get("/openapi", OpenApiSpex.Plug.RenderSpec, [])
@@ -152,7 +147,6 @@ defmodule NervesHubWeb.Router do
 
               get("/", ProductController, :show)
               delete("/", ProductController, :delete)
-              put("/", ProductController, :update)
 
               scope "/devices" do
                 get("/", DeviceController, :index)

lib/nerves_hub_web/router.ex

@@ -0,0 +1,11 @@
+defmodule NervesHubWeb.Plugs.ImAliveTest do
+  use NervesHubWeb.ConnCase, async: true
+
+  describe "GET /status/alive" do
+    test "returns 200 OK when the database is reachable", %{conn: conn} do
+      conn = get(conn, "/status/alive")
+      assert conn.status == 200
+      assert text_response(conn, 200) == "Hello, Friend!"
+    end
+  end
+end