> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rocky.global/llms.txt
> Use this file to discover all available pages before exploring further.

# SWAGGER JSON EXAMPLES

# Swagger Example Improvements - Complete JSON

## Problem Identified

The Swagger documentation did not show a complete example of the JSON returned by the API; it only showed the data type structure without a real response example.

## Solution Implemented

The Swagger documentation was updated to include complete JSON examples that show exactly what the API returns.

### Changes Made

#### 1. **Organizer API** (`/api/v1/organizer/participants`)

* **File**: `app/Http/Controllers/Api/Organizer/ParticipantsController.php`
* **Improvement**: Added a complete JSON example with `@OA\JsonContent(example={...})`

#### 2. **Supervisor API** (`/api/v1/supervisor/participants`)

* **File**: `app/Http/Controllers/Api/Supervisor/ParticipantsController.php`
* **Improvement**: Added a complete JSON example with `@OA\JsonContent(example={...})`

## Complete Example in Swagger

### Previous Structure (Types Only)

```yaml theme={null}
responses:
  200:
    description: Lista de participantes
    content:
      application/json:
        schema:
          type: object
          properties:
            data:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: integer
                    example: 403
                  event:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 4
                      name:
                        type: string
                        example: "OCEANMAN EL GOUNA - EGYPT 2025"
```

### New Structure (With Complete Example)

```yaml theme={null}
responses:
  200:
    description: Lista de participantes con información completa
    content:
      application/json:
        example:
          data:
            - id: 403
              event:
                id: 4
                name: "OCEANMAN EL GOUNA - EGYPT 2025"
              user:
                id: 322
                name: "Georgina Salah"
                lastname: ""
                email: "gsorial@aucegypt.edu"
                phone: null
                birthday: null
              registration:
                locator: "DA74ACD8"
                status: "OK"
                bib: "A-102"
                registration_date: "2025-09-26"
                created_at: "2025-09-26T04:19:24+00:00"
                created_at_human: "26/09/2025 04:19:24"
                updated_at: "2025-09-26T04:19:24+00:00"
              form_data:
                - name: "document"
                  value: "28208060100671"
                - name: "document_type"
                  value: "dni"
                - name: "country"
                  value: "Spain"
                - name: "city"
                  value: "Madrid"
          meta:
            organizer_id: 1
            filters:
              participant_id: null
              event_id: null
              status: null
              bib: null
              from: null
              to: null
              search: null
              order_by: "id"
              order_dir: "desc"
              per_page: 2000
          links:
            first: "http://api.example.com/api/v1/organizer/participants?page=1"
            last: "http://api.example.com/api/v1/organizer/participants?page=10"
            prev: null
            next: "http://api.example.com/api/v1/organizer/participants?page=2"
```

## Benefits of the Improvement

### 1. **Visual Clarity**

* Developers can see exactly what structure the API returns
* Real example with representative data
* Easy to understand the response

### 2. **Better Development Experience**

* No need to guess what the API returns
* Complete example for testing
* More useful and practical documentation

### 3. **Facilitates Integration**

* Frontend developers know exactly what to expect
* Example ready to use in tests
* Reduces development time

### 4. **More Professional Documentation**

* Swagger looks more complete and professional
* Realistic and useful examples
* Better experience for API consumers

## Example Features

### Realistic Data

* Uses data that represents a real participant
* Includes all fields of the final structure
* Shows typical values for each field

### Complete Structure

* Includes `data`, `meta`, and `links`
* Shows pagination
* Includes filters and metadata

### No Duplicates

* Reflects the removal of duplicate fields
* `form_data` only contains additional fields
* Clean and organized structure

## How to See the Improvement

### 1. **Access Swagger UI**

```
http://tu-dominio.com/api/documentation
```

### 2. **Navigate to the Participants APIs**

* `/api/v1/organizer/participants` (GET)
* `/api/v1/supervisor/participants` (GET)

### 3. **View the Example**

* Click "Try it out"
* View the complete example in the "Response" section
* The example shows exactly what the API returns

## Verification

To verify that the improvement works:

1. **Regenerate Swagger**:
   ```bash theme={null}
   php artisan l5-swagger:generate
   ```

2. **Access the documentation**:
   * Go to `/api/documentation`
   * Verify that the complete examples appear

3. **Test the API**:
   * Make a real request
   * Compare it with the shown example
   * Verify that the structure matches

## Compatibility

* ✅ Works with standard Swagger UI
* ✅ Compatible with OpenAPI 3.0
* ✅ Regenerates automatically
* ✅ Does not affect API functionality

The Swagger documentation is now much more useful and professional, showing complete and realistic examples of what the API returns.