API Docs clutter

[m-gora]

Hey MIW Contributors,

I'm starting this discussion since I just rebased development to my current feature branches.
While doing that I saw a change that introduced compound annotations to de-clutter the controllers from API Doc annotations.

This change is very much welcome, but it does not feel right to me, as it's only moving a problem to a different place.
During the design and implementation of the STS I was adding the openapi generator plugin, and configured it to create java interfaces which contains all the annotation clutter and keeps the controller classes sqeuaky clean.

Here's an example how it looks like:

Controller Implementation

@RestController
@RequiredArgsConstructor
public class SecureTokenController implements TokenApi {

  private static final String CLIENT_CREDENTIALS = "client_credentials";
  private static final String TOKEN_TYPE_BEARER = "Bearer";

  private final SecureTokenService tokenService;

  @Override
  @SneakyThrows
  public ResponseEntity<StsTokenResponse> token(
      @Valid String audience, @Valid String clientId, @Valid String clientSecret, @Valid String grantType,
      @Valid String accessToken, @Valid String bearerAccessAlias, @Valid String bearerAccessScope) {
 }

OpenAPI generator generated interface

@Generated(value = "org.openapitools.codegen.languages.SpringCodegen", date = "2023-12-05T15:46:27.691213+01:00[Europe/Berlin]")
@Validated
@Tag(name = "Secure Token Service Api", description = "the Secure Token Service Api API")
@RequestMapping("${openapi..base-path:}")
public interface TokenApi {

    /**
     * POST /token
     *
     * @param audience Audience for the SI token (required)
     * @param clientId Id of the client requesting an SI token (required)
     * @param clientSecret Secret of the client requesting an SI token (required)
     * @param grantType Type of grant: must be set to client_credentials (required)
     * @param accessToken VP access token to be added as a claim in the SI token (optional)
     * @param bearerAccessAlias Alias to be use in the sub of the VP access token (default is audience) (optional)
     * @param bearerAccessScope Scope to be added in the VP access token (optional)
     * @return The Self-Issued ID token (status code 200)
     *         or Invalid Request (status code 400)
     */
    @Operation(
        operationId = "token",
        tags = { "Secure Token Service Api" },
        responses = {
            @ApiResponse(responseCode = "200", description = "The Self-Issued ID token", content = {
                @Content(mediaType = "application/json", schema = @Schema(implementation = StsTokenResponse.class))
            }),
            @ApiResponse(responseCode = "400", description = "Invalid Request", content = {
                @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = StsTokenErrorResponse.class)))
            })
        }
    )
    @RequestMapping(
        method = RequestMethod.POST,
        value = "/token",
        produces = { "application/json" },
        consumes = { "application/x-www-form-urlencoded" }
    )
    
    ResponseEntity<StsTokenResponse> token(
        @Parameter(name = "audience", description = "Audience for the SI token", required = true) @Valid @RequestParam(value = "audience", required = true) String audience,
        @Parameter(name = "client_id", description = "Id of the client requesting an SI token", required = true) @Valid @RequestParam(value = "client_id", required = true) String clientId,
        @Parameter(name = "client_secret", description = "Secret of the client requesting an SI token", required = true) @Valid @RequestParam(value = "client_secret", required = true) String clientSecret,
        @Parameter(name = "grant_type", description = "Type of grant: must be set to client_credentials", required = true) @Valid @RequestParam(value = "grant_type", required = true) String grantType,
        @Parameter(name = "access_token", description = "VP access token to be added as a claim in the SI token") @Valid @RequestParam(value = "access_token", required = false) String accessToken,
        @Parameter(name = "bearer_access_alias", description = "Alias to be use in the sub of the VP access token (default is audience)") @Valid @RequestParam(value = "bearer_access_alias", required = false) String bearerAccessAlias,
        @Parameter(name = "bearer_access_scope", description = "Scope to be added in the VP access token") @Valid @RequestParam(value = "bearer_access_scope", required = false) String bearerAccessScope
    );

}

Since spring maps the annotations even via interfaces, we can just let them get autogenerated with the following gradle config.

openApiGenerate {
    generatorName.set('spring')
    inputSpec.set("$rootDir/docs/secure-token-service-openapi.yml")
    outputDir.set("$buildDir/generated")

    apiPackage.set('org.eclipse.tractusx.managedidentitywallets.adapter.controller')
    modelPackage.set('org.eclipse.tractusx.managedidentitywallets.adapter.controller.dto')

    configOptions.set([
        interfaceOnly: "true",
        requestMappingMode: "api_interface",
        useSpringBoot3: "true",
        skipDefaultInterface: "true"
    ])
}

To me this would be the most stable approach, as we can just regenerate api docs and interfaces from specs and don't care about it at all, while having controllers only care about the actual implementation.

Please let me know what you think.

[borisrizov-zf]

I see you've added this to the draft PR, we might have to think about the timeline for this.