fix(api-docs): use proper schema references for environment variable endpoints (#8239)

app/Http/Controllers/Api/ApplicationsController.php

@@ -19,8 +19,8 @@
 use App\Rules\ValidGitRepositoryUrl;
 use App\Services\DockerImageParser;
 use Illuminate\Http\Request;
-use Illuminate\Support\Facades\Validator;
 use Illuminate\Support\Facades\Http;
+use Illuminate\Support\Facades\Validator;
 use Illuminate\Validation\Rule;
 use OpenApi\Attributes as OA;
 use Spatie\Url\Url;
@@ -2919,10 +2919,7 @@ public function envs(Request $request)
                     new OA\MediaType(
                         mediaType: 'application/json',
                         schema: new OA\Schema(
-                            type: 'object',
+                            ref: '#/components/schemas/EnvironmentVariable'
-                            properties: [
-                                'message' => ['type' => 'string', 'example' => 'Environment variable updated.'],
-                            ]
                         )
                     ),
                 ]

app/Http/Controllers/Api/ServicesController.php

@@ -1141,10 +1141,7 @@ public function envs(Request $request)
                     new OA\MediaType(
                         mediaType: 'application/json',
                         schema: new OA\Schema(
-                            type: 'object',
+                            ref: '#/components/schemas/EnvironmentVariable'
-                            properties: [
-                                'message' => ['type' => 'string', 'example' => 'Environment variable updated.'],
-                            ]
                         )
                     ),
                 ]
@@ -1265,10 +1262,8 @@ public function update_env_by_uuid(Request $request)
                     new OA\MediaType(
                         mediaType: 'application/json',
                         schema: new OA\Schema(
-                            type: 'object',
+                            type: 'array',
-                            properties: [
+                            items: new OA\Items(ref: '#/components/schemas/EnvironmentVariable')
-                                'message' => ['type' => 'string', 'example' => 'Environment variables updated.'],
-                            ]
                         )
                     ),
                 ]

openapi.json

@@ -3063,13 +3063,7 @@
                         "content": {
                             "application\/json": {
                                 "schema": {
-                                    "properties": {
+                                    "$ref": "#\/components\/schemas\/EnvironmentVariable"
-                                        "message": {
-                                            "type": "string",
-                                            "example": "Environment variable updated."
-                                        }
-                                    },
-                                    "type": "object"
                                 }
                             }
                         }
@@ -9617,13 +9611,7 @@
                         "content": {
                             "application\/json": {
                                 "schema": {
-                                    "properties": {
+                                    "$ref": "#\/components\/schemas\/EnvironmentVariable"
-                                        "message": {
-                                            "type": "string",
-                                            "example": "Environment variable updated."
-                                        }
-                                    },
-                                    "type": "object"
                                 }
                             }
                         }
@@ -9721,13 +9709,10 @@
                         "content": {
                             "application\/json": {
                                 "schema": {
-                                    "properties": {
+                                    "type": "array",
-                                        "message": {
+                                    "items": {
-                                            "type": "string",
+                                        "$ref": "#\/components\/schemas\/EnvironmentVariable"
-                                            "example": "Environment variables updated."
+                                    }
-                                        }
-                                    },
-                                    "type": "object"
                                 }
                             }
                         }

openapi.yaml

@@ -1952,9 +1952,7 @@ paths:
           content:
             application/json:
               schema:
-                properties:
+                $ref: '#/components/schemas/EnvironmentVariable'
-                  message: { type: string, example: 'Environment variable updated.' }
-                type: object
         '401':
           $ref: '#/components/responses/401'
         '400':
@@ -6027,9 +6025,7 @@ paths:
           content:
             application/json:
               schema:
-                properties:
+                $ref: '#/components/schemas/EnvironmentVariable'
-                  message: { type: string, example: 'Environment variable updated.' }
-                type: object
         '401':
           $ref: '#/components/responses/401'
         '400':
@@ -6075,9 +6071,9 @@ paths:
           content:
             application/json:
               schema:
-                properties:
+                type: array
-                  message: { type: string, example: 'Environment variables updated.' }
+                items:
-                type: object
+                  $ref: '#/components/schemas/EnvironmentVariable'
         '401':
           $ref: '#/components/responses/401'
         '400':

tests/Feature/EnvironmentVariableUpdateApiTest.php

@@ -0,0 +1,194 @@
+<?php
+
+use App\Models\Application;
+use App\Models\Environment;
+use App\Models\EnvironmentVariable;
+use App\Models\Project;
+use App\Models\Server;
+use App\Models\Service;
+use App\Models\StandaloneDocker;
+use App\Models\Team;
+use App\Models\User;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+
+uses(RefreshDatabase::class);
+
+beforeEach(function () {
+    $this->team = Team::factory()->create();
+    $this->user = User::factory()->create();
+    $this->team->members()->attach($this->user->id, ['role' => 'owner']);
+
+    session(['currentTeam' => $this->team]);
+
+    $this->token = $this->user->createToken('test-token', ['*']);
+    $this->bearerToken = $this->token->plainTextToken;
+
+    $this->server = Server::factory()->create(['team_id' => $this->team->id]);
+    $this->destination = StandaloneDocker::factory()->create(['server_id' => $this->server->id]);
+    $this->project = Project::factory()->create(['team_id' => $this->team->id]);
+    $this->environment = Environment::factory()->create(['project_id' => $this->project->id]);
+});
+
+describe('PATCH /api/v1/services/{uuid}/envs', function () {
+    test('returns the updated environment variable object', function () {
+        $service = Service::factory()->create([
+            'server_id' => $this->server->id,
+            'destination_id' => $this->destination->id,
+            'destination_type' => $this->destination->getMorphClass(),
+            'environment_id' => $this->environment->id,
+        ]);
+
+        EnvironmentVariable::create([
+            'key' => 'APP_IMAGE_TAG',
+            'value' => 'old-value',
+            'resourceable_type' => Service::class,
+            'resourceable_id' => $service->id,
+            'is_preview' => false,
+        ]);
+
+        $response = $this->withHeaders([
+            'Authorization' => 'Bearer '.$this->bearerToken,
+            'Content-Type' => 'application/json',
+        ])->patchJson("/api/v1/services/{$service->uuid}/envs", [
+            'key' => 'APP_IMAGE_TAG',
+            'value' => 'new-value',
+        ]);
+
+        $response->assertStatus(201);
+        $response->assertJsonStructure([
+            'uuid',
+            'key',
+            'is_literal',
+            'is_multiline',
+            'is_shown_once',
+            'created_at',
+            'updated_at',
+        ]);
+        $response->assertJsonFragment(['key' => 'APP_IMAGE_TAG']);
+        $response->assertJsonMissing(['message' => 'Environment variable updated.']);
+    });
+
+    test('returns 404 when environment variable does not exist', function () {
+        $service = Service::factory()->create([
+            'server_id' => $this->server->id,
+            'destination_id' => $this->destination->id,
+            'destination_type' => $this->destination->getMorphClass(),
+            'environment_id' => $this->environment->id,
+        ]);
+
+        $response = $this->withHeaders([
+            'Authorization' => 'Bearer '.$this->bearerToken,
+            'Content-Type' => 'application/json',
+        ])->patchJson("/api/v1/services/{$service->uuid}/envs", [
+            'key' => 'NONEXISTENT_KEY',
+            'value' => 'some-value',
+        ]);
+
+        $response->assertStatus(404);
+        $response->assertJson(['message' => 'Environment variable not found.']);
+    });
+
+    test('returns 404 when service does not exist', function () {
+        $response = $this->withHeaders([
+            'Authorization' => 'Bearer '.$this->bearerToken,
+            'Content-Type' => 'application/json',
+        ])->patchJson('/api/v1/services/non-existent-uuid/envs', [
+            'key' => 'APP_IMAGE_TAG',
+            'value' => 'some-value',
+        ]);
+
+        $response->assertStatus(404);
+    });
+
+    test('returns 422 when key is missing', function () {
+        $service = Service::factory()->create([
+            'server_id' => $this->server->id,
+            'destination_id' => $this->destination->id,
+            'destination_type' => $this->destination->getMorphClass(),
+            'environment_id' => $this->environment->id,
+        ]);
+
+        $response = $this->withHeaders([
+            'Authorization' => 'Bearer '.$this->bearerToken,
+            'Content-Type' => 'application/json',
+        ])->patchJson("/api/v1/services/{$service->uuid}/envs", [
+            'value' => 'some-value',
+        ]);
+
+        $response->assertStatus(422);
+    });
+});
+
+describe('PATCH /api/v1/applications/{uuid}/envs', function () {
+    test('returns the updated environment variable object', function () {
+        $application = Application::factory()->create([
+            'environment_id' => $this->environment->id,
+            'destination_id' => $this->destination->id,
+            'destination_type' => $this->destination->getMorphClass(),
+        ]);
+
+        EnvironmentVariable::create([
+            'key' => 'APP_IMAGE_TAG',
+            'value' => 'old-value',
+            'resourceable_type' => Application::class,
+            'resourceable_id' => $application->id,
+            'is_preview' => false,
+        ]);
+
+        $response = $this->withHeaders([
+            'Authorization' => 'Bearer '.$this->bearerToken,
+            'Content-Type' => 'application/json',
+        ])->patchJson("/api/v1/applications/{$application->uuid}/envs", [
+            'key' => 'APP_IMAGE_TAG',
+            'value' => 'new-value',
+        ]);
+
+        $response->assertStatus(201);
+        $response->assertJsonStructure([
+            'uuid',
+            'key',
+            'is_literal',
+            'is_multiline',
+            'is_shown_once',
+            'created_at',
+            'updated_at',
+        ]);
+        $response->assertJsonFragment(['key' => 'APP_IMAGE_TAG']);
+        $response->assertJsonMissing(['message' => 'Environment variable updated.']);
+    });
+
+    test('returns 404 when environment variable does not exist', function () {
+        $application = Application::factory()->create([
+            'environment_id' => $this->environment->id,
+            'destination_id' => $this->destination->id,
+            'destination_type' => $this->destination->getMorphClass(),
+        ]);
+
+        $response = $this->withHeaders([
+            'Authorization' => 'Bearer '.$this->bearerToken,
+            'Content-Type' => 'application/json',
+        ])->patchJson("/api/v1/applications/{$application->uuid}/envs", [
+            'key' => 'NONEXISTENT_KEY',
+            'value' => 'some-value',
+        ]);
+
+        $response->assertStatus(404);
+    });
+
+    test('returns 422 when key is missing', function () {
+        $application = Application::factory()->create([
+            'environment_id' => $this->environment->id,
+            'destination_id' => $this->destination->id,
+            'destination_type' => $this->destination->getMorphClass(),
+        ]);
+
+        $response = $this->withHeaders([
+            'Authorization' => 'Bearer '.$this->bearerToken,
+            'Content-Type' => 'application/json',
+        ])->patchJson("/api/v1/applications/{$application->uuid}/envs", [
+            'value' => 'some-value',
+        ]);
+
+        $response->assertStatus(422);
+    });
+});