# Swagger UI Guide

> [!note] Esta página aún no está traducida y se muestra en inglés.


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.