Skip to content

Commit 4bcf136

Browse files
MMaieroMMaiero
committed
feat: add Swagger OpenAPI annotations dependencies to system REST test bundle
- Add io.swagger.v3.oas.annotations package imports to test bundle manifest - Resolve missing dependency issue preventing test compilation and execution - Import all required Swagger v3 annotation packages with version 2.1.0 - Add comprehensive OpenAPI documentation configuration and README - Update main bundle manifest and POM with proper OpenAPI dependencies Fixes compilation errors in org.eclipse.kura.rest.system.provider.test when using classes from the host bundle that reference Swagger annotations. The test bundle (fragment) needs access to the same OpenAPI annotation packages that are used by the host bundle's SystemRestService class for proper test execution. Signed-off-by: MMaiero <[email protected]>
1 parent d597953 commit 4bcf136

File tree

10 files changed

+540
-11
lines changed

10 files changed

+540
-11
lines changed

‎kura/.vscode/settings.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,6 @@
33
"editor.defaultFormatter": "redhat.java",
44
"editor.formatOnSave": true,
55
"java.debug.settings.onBuildFailureProceed": true,
6-
"java.jdt.ls.vmargs": "-XX:+UseParallelGC -XX:GCTimeRatio=4 -XX:AdaptiveSizePolicyWeight=90 -Dsun.zip.disableMemoryMapping=true -Xmx4G -Xms100m -Xlog:disable"
6+
"java.jdt.ls.vmargs": "-XX:+UseParallelGC -XX:GCTimeRatio=4 -XX:AdaptiveSizePolicyWeight=90 -Dsun.zip.disableMemoryMapping=true -Xmx4G -Xms100m -Xlog:disable",
7+
"java.configuration.updateBuildConfiguration": "interactive"
78
}

‎kura/org.eclipse.kura.rest.system.provider/META-INF/MANIFEST.MF‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,15 @@ Service-Component: OSGI-INF/*.xml
1010
Import-Package: jakarta.annotation.security;version="2.1.1",
1111
jakarta.ws.rs;version="3.1.0",
1212
jakarta.ws.rs.core;version="3.1.0",
13+
io.swagger.v3.oas.annotations;version="2.1.0",
14+
io.swagger.v3.oas.annotations.enums;version="2.1.0",
15+
io.swagger.v3.oas.annotations.info;version="2.1.0",
16+
io.swagger.v3.oas.annotations.media;version="2.1.0",
17+
io.swagger.v3.oas.annotations.parameters;version="2.1.0",
18+
io.swagger.v3.oas.annotations.responses;version="2.1.0",
19+
io.swagger.v3.oas.annotations.security;version="2.1.0",
20+
io.swagger.v3.oas.annotations.servers;version="2.1.0",
21+
io.swagger.v3.oas.annotations.tags;version="2.1.0",
1322
org.apache.commons.io;version="2.11.0",
1423
org.eclipse.kura;version="[1.3,2.0)",
1524
org.eclipse.kura.cloudconnection.request;version="[1.0,2.0)",

‎kura/org.eclipse.kura.rest.system.provider/README-OpenAPI.md‎

Lines changed: 335 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,335 @@
1+
# Eclipse Kura System REST API - OpenAPI Integration
2+
3+
## Overview
4+
5+
This document describes the OpenAPI 3.0 integration for the Eclipse Kura System REST API. The integration provides comprehensive API documentation, interactive testing capabilities, and client SDK generation support.
6+
7+
## Features
8+
9+
- **Comprehensive Documentation**: Detailed API documentation with parameter descriptions, examples, and response schemas
10+
- **Interactive Testing**: Swagger UI integration for testing endpoints directly from the browser
11+
- **Client SDK Generation**: Support for generating client libraries in multiple programming languages
12+
- **Security Documentation**: Clear documentation of authentication requirements and permissions
13+
- **Request/Response Examples**: Real-world examples for all API endpoints
14+
15+
## API Endpoints
16+
17+
### Framework Properties
18+
19+
#### GET /system/v1/properties/framework
20+
21+
Retrieves comprehensive system framework properties including hardware, Java runtime, OS, and Kura-specific information.
22+
23+
**Example Request:**
24+
```bash
25+
curl -X GET \
26+
https://localhost:8080/services/system/v1/properties/framework \
27+
-H 'Authorization: Basic YWRtaW46YWRtaW4=' \
28+
-H 'Accept: application/json'
29+
```
30+
31+
**Example Response:**
32+
```json
33+
{
34+
"biosVersion": "1.2.3",
35+
"cpuVersion": "Intel Core i7",
36+
"deviceName": "Kura-Gateway",
37+
"javaVersion": "17.0.1",
38+
"osName": "Linux",
39+
"osVersion": "5.4.0",
40+
"kuraVersion": "6.0.0-SNAPSHOT",
41+
"totalMemory": 8589934592,
42+
"freeMemory": 4294967296
43+
}
44+
```
45+
46+
#### POST /system/v1/properties/framework/filter
47+
48+
Retrieves filtered system framework properties based on specified criteria.
49+
50+
**Example Request:**
51+
```bash
52+
curl -X POST \
53+
https://localhost:8080/services/system/v1/properties/framework/filter \
54+
-H 'Authorization: Basic YWRtaW46YWRtaW4=' \
55+
-H 'Content-Type: application/json' \
56+
-H 'Accept: application/json' \
57+
-d '{
58+
"names": ["javaVersion", "osName", "kuraVersion", "totalMemory"]
59+
}'
60+
```
61+
62+
**Example Response:**
63+
```json
64+
{
65+
"javaVersion": "17.0.1",
66+
"osName": "Linux",
67+
"kuraVersion": "6.0.0-SNAPSHOT",
68+
"totalMemory": 8589934592
69+
}
70+
```
71+
72+
### Extended Properties
73+
74+
#### GET /system/v1/properties/extended
75+
76+
Retrieves extended system properties and metadata.
77+
78+
#### POST /system/v1/properties/extended/filter
79+
80+
Retrieves filtered extended properties using group-based filtering.
81+
82+
### Kura Properties
83+
84+
#### GET /system/v1/properties/kura
85+
86+
Retrieves Kura-specific configuration and runtime properties.
87+
88+
#### POST /system/v1/properties/kura/filter
89+
90+
Retrieves filtered Kura properties based on specified names.
91+
92+
## Authentication
93+
94+
All endpoints require Basic HTTP Authentication. The API uses role-based access control with the `system` role requirement.
95+
96+
**Default Credentials (Development):**
97+
- Username: `admin`
98+
- Password: `admin`
99+
100+
**Authorization Header Format:**
101+
```
102+
Authorization: Basic <base64-encoded-credentials>
103+
```
104+
105+
**Example (admin:admin):**
106+
```
107+
Authorization: Basic YWRtaW46YWRtaW4=
108+
```
109+
110+
## Building and Generating Documentation
111+
112+
### Maven Build
113+
114+
To build the project and generate OpenAPI documentation:
115+
116+
```bash
117+
# Build the project
118+
mvn clean compile
119+
120+
# Generated OpenAPI specs will be available in:
121+
# target/generated-openapi/openapi.json
122+
# target/generated-openapi/openapi.yaml
123+
```
124+
125+
### Generated Artifacts
126+
127+
After building, you'll find:
128+
129+
1. **OpenAPI JSON Specification**: `target/generated-openapi/openapi.json`
130+
2. **OpenAPI YAML Specification**: `target/generated-openapi/openapi.yaml`
131+
3. **Compiled Classes**: All OpenAPI-annotated classes with documentation metadata
132+
133+
## Integration with Swagger UI
134+
135+
To view the interactive API documentation:
136+
137+
1. **Deploy Swagger UI**: Set up Swagger UI in your web server
138+
2. **Load the OpenAPI Spec**: Point Swagger UI to the generated `openapi.json` file
139+
3. **Access Interactive Docs**: Navigate to the Swagger UI URL
140+
141+
**Example Swagger UI Configuration:**
142+
```javascript
143+
const ui = SwaggerUIBundle({
144+
url: 'path/to/openapi.json',
145+
dom_id: '#swagger-ui',
146+
deepLinking: true,
147+
presets: [
148+
SwaggerUIBundle.presets.apis,
149+
SwaggerUIStandalonePreset
150+
]
151+
});
152+
```
153+
154+
## Client SDK Generation
155+
156+
### Using OpenAPI Generator
157+
158+
Generate client SDKs using the OpenAPI Generator tool:
159+
160+
```bash
161+
# Install OpenAPI Generator
162+
npm install @openapitools/openapi-generator-cli -g
163+
164+
# Generate Java client
165+
openapi-generator-cli generate \
166+
-i target/generated-openapi/openapi.json \
167+
-g java \
168+
-o generated-clients/java \
169+
--additional-properties=packageName=org.eclipse.kura.client
170+
171+
# Generate Python client
172+
openapi-generator-cli generate \
173+
-i target/generated-openapi/openapi.json \
174+
-g python \
175+
-o generated-clients/python \
176+
--additional-properties=packageName=kura_client
177+
178+
# Generate JavaScript client
179+
openapi-generator-cli generate \
180+
-i target/generated-openapi/openapi.json \
181+
-g javascript \
182+
-o generated-clients/javascript
183+
```
184+
185+
### Available Generators
186+
187+
The OpenAPI specification supports client generation for:
188+
189+
- Java
190+
- Python
191+
- JavaScript/TypeScript
192+
- C#
193+
- Go
194+
- Ruby
195+
- PHP
196+
- Kotlin
197+
- Swift
198+
- And many more...
199+
200+
## Error Handling
201+
202+
### Standard HTTP Status Codes
203+
204+
| Code | Description | Example Scenario |
205+
|------|-------------|------------------|
206+
| 200 | Success | Request completed successfully |
207+
| 400 | Bad Request | Invalid filter parameters |
208+
| 401 | Unauthorized | Missing or invalid authentication |
209+
| 403 | Forbidden | Insufficient permissions (not in 'system' role) |
210+
| 404 | Not Found | Endpoint doesn't exist |
211+
| 500 | Internal Server Error | System service unavailable |
212+
213+
### Error Response Format
214+
215+
```json
216+
{
217+
"error": {
218+
"code": 400,
219+
"message": "Bad request - Invalid filter parameters",
220+
"details": "The 'names' array cannot be empty when specified"
221+
}
222+
}
223+
```
224+
225+
## Best Practices
226+
227+
### 1. API Versioning
228+
- Always specify API version in URLs (`/system/v1/...`)
229+
- Update version when making breaking changes
230+
- Maintain backward compatibility when possible
231+
232+
### 2. Security
233+
- Use HTTPS in production environments
234+
- Implement proper authentication and authorization
235+
- Follow principle of least privilege for role assignments
236+
237+
### 3. Performance
238+
- Use filtered endpoints when you only need specific properties
239+
- Implement proper caching strategies for frequently accessed data
240+
- Monitor API performance and usage patterns
241+
242+
### 4. Documentation Maintenance
243+
- Keep OpenAPI annotations synchronized with code changes
244+
- Update examples when API behavior changes
245+
- Review and update documentation during code reviews
246+
247+
## Development Workflow
248+
249+
### Adding New Endpoints
250+
251+
1. **Create the endpoint method** with JAX-RS annotations
252+
2. **Add OpenAPI annotations**:
253+
- `@Operation` for method documentation
254+
- `@ApiResponses` for response documentation
255+
- `@RequestBody` for request body documentation
256+
- `@Parameter` for path/query parameters
257+
258+
3. **Update DTOs** with `@Schema` annotations
259+
4. **Rebuild** to generate updated OpenAPI spec
260+
5. **Test** using Swagger UI or generated clients
261+
262+
### Example New Endpoint
263+
264+
```java
265+
@GET
266+
@Path("/status")
267+
@Produces(MediaType.APPLICATION_JSON)
268+
@Operation(
269+
summary = "Get System Status",
270+
description = "Retrieves current system status and health information"
271+
)
272+
@ApiResponses(value = {
273+
@ApiResponse(
274+
responseCode = "200",
275+
description = "System status retrieved successfully",
276+
content = @Content(schema = @Schema(implementation = SystemStatusDTO.class))
277+
)
278+
})
279+
public SystemStatusDTO getSystemStatus() {
280+
// Implementation
281+
}
282+
```
283+
284+
## Troubleshooting
285+
286+
### Common Issues
287+
288+
1. **OpenAPI Generation Fails**
289+
- Check that all referenced classes have proper `@Schema` annotations
290+
- Verify Maven dependencies are correctly configured
291+
- Review compilation errors in the build log
292+
293+
2. **Swagger UI Not Loading**
294+
- Verify the OpenAPI spec file is accessible
295+
- Check for CORS issues when loading from different domains
296+
- Validate the generated OpenAPI JSON/YAML syntax
297+
298+
3. **Authentication Issues**
299+
- Verify Basic Auth credentials are correctly encoded
300+
- Check that the user has the required `system` role
301+
- Ensure the Kura user management service is running
302+
303+
### Debugging Tips
304+
305+
- Enable debug logging for the SystemRestService class
306+
- Use browser developer tools to inspect API requests/responses
307+
- Validate OpenAPI specs using online validators
308+
- Test endpoints individually before integration testing
309+
310+
## Future Enhancements
311+
312+
### Planned Features
313+
314+
1. **Additional API Endpoints**: Network status, component health, metrics
315+
2. **Enhanced Security**: OAuth2/JWT support, API key authentication
316+
3. **Real-time Updates**: WebSocket support for live system monitoring
317+
4. **Advanced Filtering**: Query language support, pagination
318+
5. **API Rate Limiting**: Request throttling and usage quotas
319+
320+
### Contributing
321+
322+
To contribute to the OpenAPI integration:
323+
324+
1. Follow existing annotation patterns and conventions
325+
2. Add comprehensive documentation to all new endpoints
326+
3. Include realistic examples in all `@Schema` annotations
327+
4. Test generated documentation with Swagger UI
328+
5. Update this README with any new features or changes
329+
330+
## Resources
331+
332+
- [OpenAPI 3.0 Specification](https://swagger.io/specification/)
333+
- [Swagger Annotations Documentation](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations)
334+
- [Eclipse Kura Documentation](https://eclipse.github.io/kura/)
335+
- [JAX-RS Reference](https://jakarta.ee/specifications/restful-ws/)

0 commit comments

Comments
 (0)