Example JSON-LD documents in new Management API

[paullatzelsperger]

Our new Management API is lacking in terms of OpenAPI/Swagger documentation in the following aspect:
we are now using JSON-LD, which implies the use of JsonObjects, which are inherently generic. So far, we've skirted around the problem by listing the actual Dto as @Schema in the OpenAPI annotations, but that is not quite right either, because it simply does not show how the actual JSON-LD structure would look like.

I propose the following:

• Generate an exemplary JSON-LD structure, e.g. by running the API end2end tests, and copying the result
• have a (package-private) constants file that contains the example JSON
• Add an @ExampleObject to the @Content object of either the request or the response

Using the Catalog endpoint, that would look like this

@OpenAPIDefinition
@Tag(name = "Catalog")
public interface CatalogApi {
    // move this to a separate class
    String EXAMPLE_CATALOG = """
    {
      "@id": "2597a43f-55e6-46d1-a7c9-e2084e04d8fc",
      "@type": "dcat:Catalog",
      "dcat:dataset": {
        "@id": "76aeea10-1700-4a79-a5fd-7734400f2abd",
        "@type": "dcat:Dataset",
        "odrl:hasPolicy": {
          "@id": "acd02d7d-1605-4f33-a4fd-58f230cd89a9:id-2:240a5888-facb-41df-aee8-f1694b04f87b",
          "@type": "odrl:Set",
          "odrl:permission": [],
          "odrl:prohibition": [],
          "odrl:obligation": [],
          "odrl:target": "id-2"
        },
        "dcat:distribution": [],
        "edc:id": "id-2"
      },
      "dcat:service": {
        "@id": "90bc6f61-017f-417d-97cc-171fef59ee65",
        "@type": "dcat:DataService",
        "dct:terms": "connector",
        "dct:endpointUrl": "http://localhost:42427/protocol"
      },
      "edc:participantId": "anonymous",
      "@context": {
        "dct": "https://purl.org/dc/terms/",
        "edc": "https://w3id.org/edc/v0.0.1/ns/",
        "dcat": "https://www.w3.org/ns/dcat/",
        "odrl": "http://www.w3.org/ns/odrl/2/",
        "dspace": "https://w3id.org/dspace/v0.8/"
      }
    }
    """;

    @Operation(
            requestBody = @RequestBody(content = @Content(schema = @Schema(implementation = CatalogRequestDto.class))),
            responses = { @ApiResponse(
                    content = @Content(
                            mediaType = "application/json",
                            schema = @Schema(implementation = Catalog.class),
                            examples = @ExampleObject(name = "example-catalog", value = EXAMPLE_CATALOG)
                    ),
                    description = "Gets contract offers (=catalog) of a single connector") }
    )
    void requestCatalog(@Valid @NotNull JsonObject requestDto, @Suspended AsyncResponse response);

Of course there is much potential to improve this, e.g. auto-generating a static JSON file for every Dto that traverses the Management API, and reading the example JSON from that file, etc.

Then, Swagger-UI will render a much better example:

[edit] this would replace the @Schema(implementation = ...) structure

[jimmarino]

Can we use text blocks (""") to make the String look better?

[paullatzelsperger]

desc updated.

[paullatzelsperger]

created issue #3146

[Wilhelmsson177]

I do not know if this really fits here, but I tried out the samples and noticed, that the type of the value of the odlr:hasPolicy key is changing depending on the amount of policies, when fetching the catalog. When it is only 1 policy it is of type odlr:Set, when there are more policies, it becomes an array. Wouldn't it be better to return an array in any way? Even if it is only of length 1?

[jimmarino]

Please open a separate discussion

[Wilhelmsson177]

==> #3158