# Swagger UI Testing Guide

## Accessing Swagger UI

Open your browser and navigate to:
```
http://localhost:8081/swagger-ui.html
```

## Important: Authentication Required

The flight search endpoint requires authentication. You need a JWT token from Keycloak.

### Quick Setup (If Keycloak is not configured yet)

For testing purposes, you can temporarily disable authentication:

1. **Option 1: Use the setup script**
   ```bash
   cd keycloak
   ./setup-keycloak.sh
   ```

2. **Option 2: Get a token manually** (see below)

---

## Flight Search Endpoint

### Endpoint Details
- **Method**: POST
- **Path**: `/api/v1/flights/search`
- **Authentication**: Required (Bearer Token)
- **Role**: AGENT or SUPER_ADMIN

### Parameters

#### Query Parameter
- **agencyId** (required): Agency UUID
  - Example: `123e4567-e89b-12d3-a456-426614174000`
  - For testing, you can use any valid UUID format

#### Request Body (JSON)

```json
{
  "origin": "MAD",
  "destination": "JFK",
  "departureDate": "2026-03-15",
  "returnDate": "2026-03-22",
  "adults": 1,
  "children": 0,
  "infants": 0,
  "cabinClass": "ECONOMY"
}
```

### Field Descriptions

| Field | Type | Required | Description | Example |
|-------|------|----------|-------------|---------|
| `origin` | string | Yes | Origin airport IATA code (3 letters) | "MAD", "JFK", "LHR" |
| `destination` | string | Yes | Destination airport IATA code (3 letters) | "JFK", "LAX", "CDG" |
| `departureDate` | string | Yes | Departure date (YYYY-MM-DD, must be future) | "2026-03-15" |
| `returnDate` | string | No | Return date (YYYY-MM-DD, for round trips) | "2026-03-22" |
| `adults` | integer | Yes | Number of adult passengers (min: 1) | 1, 2, 3 |
| `children` | integer | No | Number of children (2-11 years) | 0, 1, 2 |
| `infants` | integer | No | Number of infants (under 2 years) | 0, 1 |
| `cabinClass` | string | No | Cabin class preference | "ECONOMY", "PREMIUM_ECONOMY", "BUSINESS", "FIRST" |

### Valid Cabin Classes
- `ECONOMY` - Economy class
- `PREMIUM_ECONOMY` - Premium economy
- `BUSINESS` - Business class
- `FIRST` - First class

---

## Example Requests

### Example 1: One-Way Economy Flight
```json
{
  "origin": "MAD",
  "destination": "JFK",
  "departureDate": "2026-03-15",
  "adults": 1,
  "children": 0,
  "infants": 0,
  "cabinClass": "ECONOMY"
}
```

**Query Parameter:**
```
agencyId=123e4567-e89b-12d3-a456-426614174000
```

### Example 2: Round-Trip with Multiple Passengers
```json
{
  "origin": "LHR",
  "destination": "DXB",
  "departureDate": "2026-04-10",
  "returnDate": "2026-04-20",
  "adults": 2,
  "children": 1,
  "infants": 0,
  "cabinClass": "BUSINESS"
}
```

**Query Parameter:**
```
agencyId=123e4567-e89b-12d3-a456-426614174000
```

### Example 3: Family Trip
```json
{
  "origin": "CDG",
  "destination": "BCN",
  "departureDate": "2026-05-01",
  "returnDate": "2026-05-08",
  "adults": 2,
  "children": 2,
  "infants": 1,
  "cabinClass": "ECONOMY"
}
```

**Query Parameter:**
```
agencyId=123e4567-e89b-12d3-a456-426614174000
```

### Example 4: Popular Routes

#### Madrid to New York
```json
{
  "origin": "MAD",
  "destination": "JFK",
  "departureDate": "2026-03-15",
  "adults": 1,
  "children": 0,
  "infants": 0,
  "cabinClass": "ECONOMY"
}
```

#### London to Dubai
```json
{
  "origin": "LHR",
  "destination": "DXB",
  "departureDate": "2026-04-01",
  "returnDate": "2026-04-15",
  "adults": 1,
  "children": 0,
  "infants": 0,
  "cabinClass": "BUSINESS"
}
```

#### Paris to Tokyo
```json
{
  "origin": "CDG",
  "destination": "NRT",
  "departureDate": "2026-06-10",
  "returnDate": "2026-06-25",
  "adults": 2,
  "children": 0,
  "infants": 0,
  "cabinClass": "PREMIUM_ECONOMY"
}
```

---

## Step-by-Step: Testing in Swagger UI

### Step 1: Get Authentication Token

First, you need to get a JWT token from Keycloak:

```bash
# Get token from Keycloak
curl -X POST "http://localhost:8080/realms/b2b-flight-platform/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id=b2b-flight-backend" \
  -d "client_secret=b2b-flight-backend-secret" \
  -d "username=agent@test.com" \
  -d "password=password123"
```

This will return a JSON response with an `access_token`. Copy this token.

### Step 2: Authorize in Swagger UI

1. Open Swagger UI: http://localhost:8081/swagger-ui.html
2. Click the **"Authorize"** button (lock icon) at the top right
3. In the "Value" field, enter: `Bearer YOUR_ACCESS_TOKEN`
   - Replace `YOUR_ACCESS_TOKEN` with the token from Step 1
4. Click **"Authorize"**
5. Click **"Close"**

### Step 3: Find the Flight Search Endpoint

1. Scroll down to the **"Flight Search"** section
2. Click on **POST /api/v1/flights/search**
3. Click **"Try it out"**

### Step 4: Fill in the Parameters

#### Query Parameter (agencyId):
```
123e4567-e89b-12d3-a456-426614174000
```

#### Request Body:
```json
{
  "origin": "MAD",
  "destination": "JFK",
  "departureDate": "2026-03-15",
  "returnDate": "2026-03-22",
  "adults": 1,
  "children": 0,
  "infants": 0,
  "cabinClass": "ECONOMY"
}
```

### Step 5: Execute the Request

1. Click the **"Execute"** button
2. Wait for the response (may take 5-10 seconds)
3. Review the response below

---

## Expected Response

### Success Response (200 OK)

```json
{
  "searchId": "search-123e4567-e89b-12d3-a456-426614174000",
  "offers": [
    {
      "offerId": "offer-abc123",
      "validatingCarrier": "AV",
      "price": {
        "baseFare": 266.66,
        "taxes": 50.00,
        "markup": 15.83,
        "total": 332.49,
        "currency": "EUR"
      },
      "outboundSegments": [
        {
          "departureAirport": "MAD",
          "arrivalAirport": "BOG",
          "departureTime": "2026-03-15T10:50:00",
          "arrivalTime": "2026-03-15T15:05:00",
          "carrierCode": "AV",
          "flightNumber": "183",
          "cabinClass": "ECONOMY",
          "duration": "PT10H15M"
        },
        {
          "departureAirport": "BOG",
          "arrivalAirport": "JFK",
          "departureTime": "2026-03-15T17:00:00",
          "arrivalTime": "2026-03-15T23:45:00",
          "carrierCode": "AV",
          "flightNumber": "244",
          "cabinClass": "ECONOMY",
          "duration": "PT5H45M"
        }
      ],
      "inboundSegments": [
        {
          "departureAirport": "JFK",
          "arrivalAirport": "MAD",
          "departureTime": "2026-03-22T18:00:00",
          "arrivalTime": "2026-03-23T08:30:00",
          "carrierCode": "IB",
          "flightNumber": "6251",
          "cabinClass": "ECONOMY",
          "duration": "PT7H30M"
        }
      ]
    }
  ],
  "expiresAt": "2026-03-14T15:30:00"
}
```

### Error Responses

#### 400 Bad Request - Invalid Parameters
```json
{
  "timestamp": "2026-01-23T15:30:00",
  "status": 400,
  "error": "Bad Request",
  "message": "Departure date must be in the future",
  "path": "/api/v1/flights/search"
}
```

#### 401 Unauthorized - Missing Token
```json
{
  "timestamp": "2026-01-23T15:30:00",
  "status": 401,
  "error": "Unauthorized",
  "message": "Full authentication is required to access this resource",
  "path": "/api/v1/flights/search"
}
```

#### 403 Forbidden - Insufficient Permissions
```json
{
  "timestamp": "2026-01-23T15:30:00",
  "status": 403,
  "error": "Forbidden",
  "message": "Access denied. Required role: AGENT",
  "path": "/api/v1/flights/search"
}
```

---

## Common Airport Codes

### Europe
- **MAD** - Madrid, Spain
- **BCN** - Barcelona, Spain
- **LHR** - London Heathrow, UK
- **CDG** - Paris Charles de Gaulle, France
- **FRA** - Frankfurt, Germany
- **AMS** - Amsterdam, Netherlands
- **FCO** - Rome, Italy

### Americas
- **JFK** - New York JFK, USA
- **LAX** - Los Angeles, USA
- **MIA** - Miami, USA
- **ORD** - Chicago, USA
- **YYZ** - Toronto, Canada
- **MEX** - Mexico City, Mexico
- **GRU** - São Paulo, Brazil

### Asia & Middle East
- **DXB** - Dubai, UAE
- **DOH** - Doha, Qatar
- **NRT** - Tokyo Narita, Japan
- **SIN** - Singapore
- **HKG** - Hong Kong
- **BKK** - Bangkok, Thailand
- **DEL** - Delhi, India

---

## Troubleshooting

### Issue: "Full authentication is required"
**Solution**: You need to authorize in Swagger UI with a valid JWT token.

### Issue: "Departure date must be in the future"
**Solution**: Use a date in the future (e.g., 2026-03-15 or later).

### Issue: "Origin airport code is required"
**Solution**: Make sure all required fields are filled in the request body.

### Issue: "Agency inactive or insufficient permissions"
**Solution**: 
1. Make sure the agencyId exists in the database
2. Ensure your user has AGENT or SUPER_ADMIN role
3. Check that the agency is active and verified

### Issue: "Amadeus API unavailable"
**Solution**: 
1. Check application health: http://localhost:8081/actuator/health
2. Verify Amadeus credentials in .env file
3. Check application logs: `docker-compose logs app`

---

## Quick Test Without Authentication

If you want to test quickly without setting up Keycloak, you can temporarily modify the SecurityConfig to allow public access to the flight search endpoint.

**Note**: This is for testing only and should NOT be used in production!

---

## Next Steps After Successful Search

1. **View Offer Details**: Use the `offerId` from the response
   ```
   GET /api/v1/flights/offers/{offerId}
   ```

2. **Check Fare Rules**: Review cancellation and change policies
   ```
   GET /api/v1/flights/offers/{offerId}/fare-rules
   ```

3. **Create Booking**: Use the offer to create a booking
   ```
   POST /api/v1/bookings
   ```

4. **Issue Ticket**: After booking confirmation
   ```
   POST /api/v1/tickets/issue
   ```

---

## Additional Resources

- **API Documentation**: http://localhost:8081/api-docs
- **Application Health**: http://localhost:8081/actuator/health
- **Keycloak Admin**: http://localhost:8080/admin
- **RabbitMQ Management**: http://localhost:15672

---

**Last Updated**: January 23, 2026