Feature | Extend Swagger Coverage for controller OAuth2ElectionsApiController…

app/Swagger/ElectionSchemas.php

@@ -0,0 +1,69 @@
+<?php
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+
+
+
+#[OA\Schema(
+    schema: 'CandidateProfileUpdateRequest',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'bio', type: 'string', description: 'Candidate biography'),
+        new OA\Property(property: 'relationship_to_openstack', type: 'string', description: 'Relationship to OpenStack'),
+        new OA\Property(property: 'experience', type: 'string', description: 'Professional experience'),
+        new OA\Property(property: 'boards_role', type: 'string', description: 'Board role experience'),
+        new OA\Property(property: 'top_priority', type: 'string', description: 'Top priority if elected'),
+    ]
+)]
+class CandidateProfileUpdateRequestSchema {}
+
+#[OA\Schema(
+    schema: 'NominationRequest',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'comment', type: 'string', nullable: true, description: 'Optional comment for the nomination'),
+    ]
+)]
+class NominationRequestSchema {}
+
+
+#[OA\Schema(
+    schema: "PaginatedElectionsResponse",
+    allOf: [
+        new OA\Schema(ref: '#/components/schemas/PaginateDataSchemaResponse'),
+        new OA\Schema(
+            type: 'object',
+            properties: [
+                new OA\Property(
+                    property: "data",
+                    type: "array",
+                    items: new OA\Items(ref: "#/components/schemas/Election")
+                )
+            ]
+        )]
+)]
+class PaginatedElectionsResponseSchema
+{
+}
+
+
+#[OA\Schema(
+    schema: "PaginatedCandidatesResponse",
+    allOf: [
+        new OA\Schema(ref: '#/components/schemas/PaginateDataSchemaResponse'),
+        new OA\Schema(
+            type: 'object',
+            properties: [
+                new OA\Property(
+                    property: "data",
+                    type: "array",
+                    items: new OA\Items(ref: "#/components/schemas/Candidate")
+                )
+            ]
+        )]
+)]
+class PaginatedCandidatesResponseSchema
+{
+}

app/Swagger/Models/CandidateSchema.php

@@ -0,0 +1,105 @@
+<?php
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: "Candidate",
+    type: "object",
+    required: ["id", "member_id", "election_id"],
+    properties: [
+        new OA\Property(
+            property: "id",
+            type: "integer",
+            format: "int64",
+            description: "Candidate ID",
+            example: 1
+        ),
+        new OA\Property(
+            property: "member_id",
+            type: "integer",
+            format: "int64",
+            description: "Associated member ID",
+            example: 123
+        ),
+        new OA\Property(
+            property: "election_id",
+            type: "integer",
+            format: "int64",
+            description: "Associated election ID",
+            example: 1
+        ),
+        new OA\Property(
+            property: "has_accepted_nomination",
+            type: "boolean",
+            description: "Whether candidate has accepted nomination",
+            example: true
+        ),
+        new OA\Property(
+            property: "is_gold_member",
+            type: "boolean",
+            description: "Whether candidate is featured/gold",
+            example: false
+        ),
+        new OA\Property(
+            property: "relationship_to_openstack",
+            type: "string",
+            nullable: true,
+            description: "Relationship to OpenStack",
+            example: "Core contributor"
+        ),
+        new OA\Property(
+            property: "experience",
+            type: "string",
+            nullable: true,
+            description: "Professional experience",
+            example: "10 years in open source"
+        ),
+        new OA\Property(
+            property: "boards_role",
+            type: "string",
+            nullable: true,
+            description: "Board role experience",
+            example: "Board member for 3 years"
+        ),
+        new OA\Property(
+            property: "bio",
+            type: "string",
+            nullable: true,
+            description: "Candidate biography",
+            example: "Passionate OpenStack contributor"
+        ),
+        new OA\Property(
+            property: "top_priority",
+            type: "string",
+            nullable: true,
+            description: "Top priority if elected",
+            example: "Improve community engagement"
+        ),
+        new OA\Property(
+            property: "created_at",
+            type: "integer",
+            format: "int64",
+            description: "Creation timestamp (unix epoch)"
+        ),
+        new OA\Property(
+            property: "updated_at",
+            type: "integer",
+            format: "int64",
+            description: "Last update timestamp (unix epoch)"
+        ),
+        new OA\Property(
+            property: "member",
+            description: "Member details (only when expand=member)",
+            ref: "#/components/schemas/Member",
+            nullable: true
+        ),
+        new OA\Property(
+            property: "election",
+            description: "Election details (only when expand=election)",
+            ref: "#/components/schemas/Election",
+            nullable: true
+        ),
+    ]
+)]
+class CandidateSchema {}

app/Swagger/Models/ElectionSchema.php

@@ -0,0 +1,102 @@
+<?php
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: "Election",
+    type: "object",
+    required: ["id", "name"],
+    properties: [
+        new OA\Property(
+            property: "id",
+            type: "integer",
+            format: "int64",
+            example: 1
+        ),
+        new OA\Property(
+            property: "name",
+            type: "string",
+            example: "Board Election 2025"
+        ),
+        new OA\Property(
+            property: "status",
+            type: "string",
+            enum: ["open", "closed", "upcoming"],
+            example: "open"
+        ),
+        new OA\Property(
+            property: "opens",
+            type: "integer",
+            format: "int64",
+            description: "Unix timestamp when election opens",
+            example: 1634567890
+        ),
+        new OA\Property(
+            property: "closes",
+            type: "integer",
+            format: "int64",
+            description: "Unix timestamp when election closes",
+            example: 1634654290
+        ),
+        new OA\Property(
+            property: "nomination_opens",
+            type: "integer",
+            format: "int64",
+            description: "Unix timestamp when nominations open",
+            example: 1634481490
+        ),
+        new OA\Property(
+            property: "nomination_closes",
+            type: "integer",
+            format: "int64",
+            description: "Unix timestamp when nominations close",
+            example: 1634567890
+        ),
+        new OA\Property(
+            property: "nomination_application_deadline",
+            type: "integer",
+            format: "int64",
+            description: "Unix timestamp for nomination application deadline",
+            example: 1634567890
+        ),
+        new OA\Property(
+            property: "candidate_application_form_relationship_to_openstack_label",
+            type: "string",
+            example: "Relationship to OpenStack"
+        ),
+        new OA\Property(
+            property: "candidate_application_form_experience_label",
+            type: "string",
+            example: "Experience in OpenStack"
+        ),
+        new OA\Property(
+            property: "candidate_application_form_boards_role_label",
+            type: "string",
+            example: "Board Role Experience"
+        ),
+        new OA\Property(
+            property: "candidate_application_form_top_priority_label",
+            type: "string",
+            example: "Top Priorities"
+        ),
+        new OA\Property(
+            property: "nominations_limit",
+            type: "integer",
+            example: 10
+        ),
+        new OA\Property(
+            property: "created_at",
+            type: "integer",
+            format: "int64",
+            description: "Creation timestamp"
+        ),
+        new OA\Property(
+            property: "updated_at",
+            type: "integer",
+            format: "int64",
+            description: "Last update timestamp"
+        ),
+    ]
+)]
+class ElectionSchema {}

app/Swagger/NominationSchema.php

@@ -0,0 +1,79 @@
+<?php
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+
+#[OA\Schema(
+    schema: "Nomination",
+    type: "object",
+    required: ["id", "candidate_id", "nominator_id", "election_id"],
+    properties: [
+        new OA\Property(
+            property: "id",
+            type: "integer",
+            format: "int64",
+            description: "Nomination ID",
+            example: 1
+        ),
+        new OA\Property(
+            property: "election_id",
+            type: "integer",
+            format: "int64",
+            description: "Associated election ID",
+            example: 1
+        ),
+        new OA\Property(
+            property: "candidate_id",
+            type: "integer",
+            format: "int64",
+            description: "Nominated candidate ID",
+            example: 123
+        ),
+        new OA\Property(
+            property: "nominator_id",
+            type: "integer",
+            format: "int64",
+            description: "Member who made the nomination",
+            example: 456
+        ),
+        new OA\Property(
+            property: "comment",
+            type: "string",
+            nullable: true,
+            description: "Optional nomination comment",
+            example: "Great candidate for the board"
+        ),
+        new OA\Property(
+            property: "created_at",
+            type: "integer",
+            format: "int64",
+            description: "Creation timestamp (unix epoch)"
+        ),
+        new OA\Property(
+            property: "updated_at",
+            type: "integer",
+            format: "int64",
+            description: "Last update timestamp (unix epoch)"
+        ),
+        new OA\Property(
+            property: "election",
+            description: "Expanded election object (only with expand=election)",
+            ref: "#/components/schemas/Election",
+            nullable: true
+        ),
+        new OA\Property(
+            property: "candidate",
+            description: "Expanded candidate object (only with expand=candidate)",
+            ref: "#/components/schemas/Candidate",
+            nullable: true
+        ),
+        new OA\Property(
+            property: "nominator",
+            description: "Expanded nominator member object (only with expand=nominator)",
+            ref: "#/components/schemas/Member",
+            nullable: true
+        ),
+    ]
+)]
+class NominationSchema {}

app/Swagger/Security/ElectionOAuth2Schema.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace App\Swagger\security;
+
+use App\Security\ElectionScopes;
+use OpenApi\Attributes as OA;
+
+#[
+    OA\SecurityScheme(
+        type: 'oauth2',
+        securityScheme: 'election_oauth2',
+        flows: [
+            new OA\Flow(
+                authorizationUrl: L5_SWAGGER_CONST_AUTH_URL,
+                tokenUrl: L5_SWAGGER_CONST_TOKEN_URL,
+                flow: 'authorizationCode',
+                scopes: [
+                    ElectionScopes::ReadAllElections => 'Read All Elections',
+                    ElectionScopes::WriteMyCandidateProfile => 'Write My Candidate Profile',
+                    ElectionScopes::NominatesCandidates => 'Nominate Candidates',
+                ],
+            ),
+        ],
+    )
+]
+class ElectionOAuth2Schema {}