# Swagger UI Guide

> [!note] Deze pagina is nog niet in het Nederlands beschikbaar en wordt in het Engels weergegeven.


This guide explains how to use the interactive Swagger UI to explore, test, and understand the Elements Hub REST API without writing any code.

## Accessing Swagger UI

### 1. Start Elements Hub Server

Ensure your Elements Hub server is running. By default, it runs on [http://localhost:42042](http://localhost:42042)

> [!note] Replace localhost:42042 with your actual server address and port.

### 2. Open Swagger UI
Navigate to the Swagger UI in your web browser: [http://localhost:42042/swagger/](http://localhost:42042/swagger/)\
The server automatically redirects the root URL (`/`) to the Swagger UI, so you can also simply visit: [http://localhost:42042](http://localhost:42042)

![Swagger UI](../_images/1758204210663-swagger-ui.png)

## Swagger UI Interface Overview

### Main Components

The Swagger UI interface consists of several key sections:

1. **API Information Header**
   - API title and version
   - Server information
   - Base URL

2. **Endpoint Groups (Tags)**
   - Organized by functionality (System, Lifecycle, Devices, etc.)
   - Collapsible sections for better navigation

3. **Individual Endpoints**
   - HTTP method and path
   - Brief description
   - Parameters and response information

4. **Global Controls**
   - Authorization settings
   - Server selection
   - Response format options

## Exploring API Endpoints

### Expanding Endpoint Groups
Click on any endpoint group to expand it and see the available operations.

### Understanding HTTP Methods

Each endpoint shows its HTTP method with colour coding:
- **🟢 GET** (Green) - Retrieve data
- **🔵 POST** (Blue) - Create or trigger operations
- **🟡 PUT** (Yellow) - Update existing resources
- **🔴 DELETE** (Red) - Remove resources

### Viewing Endpoint Details

Click on any individual endpoint to expand its details:

![Open GET](../_images/1758204963242-swagger-ui-open.png)

## Testing API Endpoints

### Simple GET Request Example

Let's test the system version endpoint:

1. **Expand the System group** and click on `GET /v1/system/version`

2. **Click "Try it out"** button
![Try it out](../_images/1758205633602-swagger-ui-try-it.png)

3. **Click "Execute"** to make the request
![Execute GET](../_images/1758205861241-swagger-ui-execute.png)

The response will show:
- **Response Code** (e.g., 200 for success)
- **Response Body** with the actual data
- **Response Headers**
- **Request URL** that was called

![GET response](../_images/1758205951464-swagger-ui-get-response.png)

### POST Request with Parameters

Let's test initialising the lifecycle services:
1. **Expand the Lifecycle group** and click on `POST /v1/lifecycle/initialize`
2. **Click "Try it out"**
3. **Edit the request body** in the text area:
```json
{
  "dataDirectory": "C:\\ProgramData\\ElementsHub\\Data",
  "logDirectory": "C:\\ProgramData\\ElementsHub\\Logs"
}
```

![POST with payload](../_images/1758206445946-swagger-ui-payload.png)

4. **Click "Execute"**

### POST Request with Path Parameters
For endpoints that require path parameters:
1. **Expand Connected Devices** and click on `GET /v1/devices/{deviceId}`
2. **Click "Try it out"**
3. **Enter the device ID** in the parameter field
4. **Click "Execute"**

## Understanding Request and Response Schemas

### Request Body Schemas

When an endpoint accepts a request body, Swagger UI shows:

- **Property names** and their types
- **Required fields** (marked with \*)
- **Example values**
- **Property descriptions**

You can click on the schema to see more details and copy the example JSON.

### Response Schemas

Each endpoint shows possible response codes and their schemas:

- **200 Success** responses with data structure
- **400 Bad Request** error format
- **404 Not Found** responses
- **Other status codes** as applicable

## Working with Different Content Types

### Image Responses

Some endpoints return images (like device camera captures):

1. **Navigate to** `GET /v1/devices/{deviceId}/images/latest`

2. **Select the appropriate Accept header** (e.g., `image/jpeg`)

3. **Execute the request**

The response will show the image data or provide a download link.

### File Downloads

For endpoints that return files, Swagger UI will provide options to download or view the file content.

## Error Handling and Debugging

### Common Error Responses
When requests fail, Swagger UI displays helpful error information.

### Request Validation Errors
If your request doesn't match the expected schema, Swagger UI will highlight:
- Missing required fields
- Invalid data types
- Out-of-range values
- Format violations

### Network and Server Errors
For connectivity issues check:
- Server is running
- Correct URL and port
- Network connectivity
- Firewall settings

## Advanced Features
### Multiple API Versions

If multiple API versions are available, you can switch between them:

### Server Selection
If multiple servers are configured, you can select which one to use:

### Downloading OpenAPI Specification

You can download the raw OpenAPI specification:
Look for a link to download the `swagger.json` file for use with code generators.

## Best Practices for Testing

### 1. Start with System Endpoints

Always begin by testing basic system endpoints:
- `GET /v1/system/version` - Verify server is running
- `POST /v1/lifecycle/initialize` - Initialize services

### 2. Follow the Logical Flow

For device operations, follow this sequence:
1. Initialize lifecycle services
2. Start a device scan
3. Check available devices
4. Connect to a device
5. Perform device operations
6. Disconnect when done

### 3. Check Dependencies
Some endpoints depend on others being called first:
- Device operations require initialization.
- Device connections require scanning.
- Measurements require connected devices.

### 4. Use Realistic Test Data
When testing with sample data:
- Use valid file paths for directory parameters.
- Use realistic device identifiers.
- Follow the expected data formats.

### 5. Monitor Response Times
Pay attention to response times for operations:
- Some operations (like device scanning) may take time.
- Check for appropriate timeout handling.
- Consider async patterns for long-running operations.

## Troubleshooting Common Issues
### "Try it out" Button Not Working
- Ensure JavaScript is enabled in your browser.
- Check for browser console errors (press `F12` on your keyboard).
- Try refreshing the page.

### CORS Errors
If testing from a different domain:
- CORS may need to be configured on the server or proxy.
- Try accessing from the same domain as the API.

### Large Response Handling
For endpoints that return large amounts of data:
- UI may slow down or freeze.
- Responses may be truncated in the UI.
- Consider using dedicated API clients for large data sets.
- Check response size limits.

## Integrating with Development Workflow
### Documentation and Discovery
Use Swagger UI for:
- **API Documentation** - Understanding available endpoints.
- **Schema Discovery** - Learning request/response formats.
- **Quick Testing** - Validating API behaviour.
- **Example Generation** - Getting sample requests for development.

### Code Generation Preparation
After exploring with Swagger UI:
1. Download the OpenAPI specification.
2. Use it with code generators (see chapter Client Code Generation).
3. Reference the tested examples in your generated clients.

## Tips for Effective API Exploration
### 1. Start Simple
Begin with read-only operations (GET requests) before attempting modifications.

### 2. Keep Notes
Document successful request patterns for later reference in your applications.

### 3. Test Edge Cases
Try invalid inputs to understand error handling and validation rules.

### 4. Understand State
Some operations change system state - be aware of the order of operations.

### 5. Use Browser Developer Tools
Monitor network requests in browser development tools for additional debugging information.