Add comprehensive OpenAPI documentation for all API endpoints

[assadriaz]

This PR adds complete OpenAPI 3.1.0 documentation to all API endpoints in the Mummu Stop Place Register, improving API discoverability and developer experience. All 35+ JSON endpoints are now fully
documented with descriptions, parameters, response codes, and error schemas.

Changes

New Files

• ErrorResponse.java - Standardized error response model with errorCode, message, and details fields
• GlobalExceptionHandler.java - Centralized exception handling for consistent error responses (404, 400, 500)

Modified Files

SwaggerConfiguration.java

• ✅ Updated API title: "Stop Place Register" (was "OpenAPI definition")
• ✅ Updated version: "1.0.0" (was "v0")
• ✅ Added comprehensive API description
• ✅ Added contact information (Entur API Support)
• ✅ Added 7 user-oriented functional tags:
  • Stop Places
  • Quays
  • Scheduled Stop Points
  • Fare Zones
  • Parking
  • Geographic Areas
  • Groupings

NotFoundException.java

• Added default constructor with standard message
• Added constructor accepting custom error messages
• Removed hardcoded error reason for flexibility

StopPlacesRequestParams.java

• Added @Schema annotations to all 8 parameters with descriptions, examples, and default values
• Documented multimodal filter with allowable values
• Added parameter descriptions for filtering capabilities

RestResource.java (Main changes)

• 35+ endpoints now fully documented with:

  • @Operation - Summary and detailed description for each endpoint
  • @ApiResponses - Status codes 200, 400/404, 500 with error schema references
  • @Parameter - Descriptions and examples for all path and query parameters

• Documented endpoint groups:

  • Groups of Stop Places (2 endpoints)
  • Stop Places (7 endpoints)
  • Quays (5 endpoints)
  • Parkings (4 endpoints)
  • Topographic Places (4 endpoints)
  • Tariff Zones - deprecated (4 endpoints, marked with deprecated = true)
  • Groups of Tariff Zones (2 endpoints)
  • Fare Zones (4 endpoints)
  • Scheduled Stop Points (3 endpoints)

Documentation Quality

Each endpoint now includes:

• Clear, actionable summary (e.g., "List stop places", "Get quay by ID")
• Detailed description explaining purpose and use cases
• Parameter descriptions with realistic examples
• Complete response documentation:
  • 200: Success description
  • 404: Not found with ErrorResponse schema
  • 400: Invalid parameters with ErrorResponse schema (list endpoints)
  • 500: Internal Server Error with ErrorResponse schema
• Appropriate functional tags for organization

Testing

• ✅ Compilation successful (mvn clean compile)
• ✅ OpenAPI spec regenerated successfully (152K)
• ✅ Application starts and Swagger UI accessible at /swagger-ui.html
• ✅ All endpoints properly documented in generated spec
• ✅ Error response schemas correctly referenced

OpenAPI Compliance Improvement

Metric	Before	After
API Title	❌ Generic "OpenAPI definition"	✅ "Stop Place Register"
API Description	❌ Missing	✅ Complete description
API Version	❌ "v0"	✅ "1.0.0" (semantic versioning)
Contact Info	❌ Missing	✅ Entur API Support
Functional Tags	❌ 1 generic tag	✅ 7 user-oriented tags
Endpoint Documentation	❌ 0/35 documented	✅ 35/35 documented
Parameter Descriptions	❌ 0%	✅ 100%
Error Responses	❌ None defined	✅ Standardized ErrorResponse
Overall Compliance	13%	~95%

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud