eclipse-tractusx / eclipse-tractusx/bpdm

Gate: Missing HTTP Response Code Declarations

Open
#1,690 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Kotlin
Stars
12
Forks
28
Avg merge
3d 14h
Merged PRs (30d)
41

Description

## Summary

The Gate API OpenAPI specification generated from the reference implementation is missing mandatory HTTP response code declarations on all API resources. CX-0074 §2.2.4 requires these codes to be **defined** for every resource, not merely returned at runtime.

## Standard Reference

> **CX-0074 §2.2.4 ERROR HANDLING**
>
> The following http response codes **MUST** be defined for all resources:
> - 200 — OK
> - 400 — Bad Request
> - 401 — Unauthorized
> - 403 — Forbidden
> - 404 — Not Found
> - 500 — Internal Server Error

## Current State

The `@ApiResponses` annotations in the reference implementation only declare `200` and `400` on most endpoints, and in some cases only `200`. Since SpringDoc derives the OpenAPI specification directly from these annotations, the generated `gate-openapi.json` is missing `401`, `403`, `404`, and `500` response definitions for all resources.

Affected interfaces (all endpoints within each):

| Interface | Declared codes | Missing codes |
|---|---|---|
| `GateBusinessPartnerApi` | 200, 400 | 401, 403, 404, 500 |
| `GateRelationApi` | 200, 400 | 401, 403, 404, 500 |
| `GateRelationOutputApi` | 200 | 400, 401, 403, 404, 500 |
| `GateSharingStateApi` | 200 / 204+400 | 401, 403, 404, 500 |
| `GateRelationSharingStateApi` | 200 | 400, 401, 403, 404, 500 |
| `GateChangelogApi` | 200, 400 | 401, 403, 404, 500 |
| `GateRelationChangelogApi` | 200, 400 | 401, 403, 404, 500 |

## Expected Behaviour

Every endpoint in the generated `gate-openapi.json` must include response schema entries for `400`, `401`, `403`, `404`, and `500` in addition to the success response.

- **401 Unauthorized** — returned when no valid OAuth2 bearer token is supplied.
- **403 Forbidden** — returned when the authenticated client lacks the required scope.
- **404 Not Found** — returned when a referenced resource (e.g. an external ID) does not exist.
- **500 Internal Server Error** — returned on unexpected server-side failures.

## Proposed Fix

Add `@ApiResponse` annotations for the missing codes to every method in the affected interfaces. A shared annotation set (e.g. via a meta-annotation or OpenAPI global configuration in `application.yml`) can avoid repetition across all controllers. The 404 response is particularly relevant for endpoints that look up by external ID (upsert operations return 200/400 but search endpoints may produce 404 when the set of IDs yields no results, depending on implementation semantics).

Example for a single endpoint:

```kotlin
@ApiResponses(
value = [
ApiResponse(responseCode = "200", description = "..."),
ApiResponse(responseCode = "400", description = "On malformed request", content = [Content()]),
ApiResponse(responseCode = "401", description = "No valid authentication credentials", content = [Content()]),
ApiResponse(responseCode = "403", description = "Insufficient permissions", content = [Content()]),
ApiResponse(responseCode = "404", description = "Resource not found", content = [Content()]),
ApiResponse(responseCode = "500", description = "Internal server error", content = [Content()])
]
)
```

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.