OpenAPI throws Could not resolve reference: Could not resolve pointer: for @ExampleObject files

Question

I am developing a Quarkus service-based application for which I am adding open API based annotations such as @ExampleObject. For this, I would like to add the resources file contents as an example that can appear in the SwaggerUI.

I am getting the following error when I add the reference to the files from the resources folder:

Errors
 
Resolver error at paths./api/generateTestData.post.requestBody.content.application/json.examples.Example1 Schema.$ref
Could not resolve reference: Could not resolve pointer: /Example1.json does not exist in document

Resolver error at paths./api/generateTestData.post.requestBody.content.application/json.examples.Example2 Schema.$ref
Could not resolve reference: Could not resolve pointer: /Example2.json does not exist in document

Following is my Quarkus based Java code:

@RequestBody(description = "InputTemplate body",
        content = @Content(schema = @Schema(implementation = InputTemplate.class), examples = {
                @ExampleObject(name = "Example-1",
                        description = "Example-1 for InputTemplate.",
                        ref = "#/resources/Example1.json"), externalValue = "#/resources/Example2.json"
                @ExampleObject(name = "Example-2",
                        description = "Example-2 for InputTemplate.",
                        ref = "#/resources/Example1.json") //externalValue = "#/resources/Example1.json"
        }))

Note: I am able to add the String as value but the content for these examples is very large so I would like to read from the files only so trying this approach.

Is there any way I can access the resources file and add it as a ref within my @ExampleObject

Answer 1

A working example below:

---

Create an OASModelFilter class which implements OASFilter:

package org.acme;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;
import org.eclipse.microprofile.openapi.OASFactory;
import org.eclipse.microprofile.openapi.OASFilter;
import org.eclipse.microprofile.openapi.models.Components;
import org.eclipse.microprofile.openapi.models.OpenAPI;

import java.io.IOException;
import java.io.InputStream;
import java.nio.charset.StandardCharsets;
import java.util.LinkedHashMap;
import java.util.Map;

import org.eclipse.microprofile.openapi.models.examples.Example;

public class OASModelFilter implements OASFilter {

    ObjectMapper objectMapper = new ObjectMapper();

    @Override
    public void filterOpenAPI(OpenAPI openAPI) {

        //openApi.getComponents() will result in NULL as we don't have any openapi.yaml file.
        Components defaultComponents = OASFactory.createComponents();
        if(openAPI.getComponents() == null){
            openAPI.setComponents(defaultComponents);
        }

        generateExamples().forEach(openAPI.getComponents()::addExample);
    }

    Map<String, Example> generateExamples() {


        Map<String, Example> examples = new LinkedHashMap<>();

        try {

            //loop over your Example JSON Files,..
            //In this case, the example is only for 1 file.
            ClassLoader loader = Thread.currentThread().getContextClassLoader();
            InputStream userJsonFileInputStream = loader.getResourceAsStream("user.json");

            String fileJSONContents = new String(userJsonFileInputStream.readAllBytes(), StandardCharsets.UTF_8);



            //Create a unique example for each File/JSON
            Example createExample = OASFactory.createExample()
                                              .description("User JSON Description")
                                              .value(objectMapper.readValue(fileJSONContents, ObjectNode.class));

            // Save your Example with a Unique Map Key.
            examples.put("createExample", createExample);

        } catch (IOException ioException) {
            System.out.println("An error occured" + ioException);
        }
        return examples;
    }

}

---

The controller using createExample as its @ExampleObject.

@Path("/hello")
public class GreetingResource {

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    @APIResponses(
            value = {
                    @APIResponse(responseCode = "200", content =  @Content(
                            mediaType = "*/*",
                            examples = {
                                    @ExampleObject(name = "boo",
                                            summary = "example of boo",
                                            ref = "createExample")
                            }

                    ))
            }
    )
    public String hello() {
        return "Hello RESTEasy";
    }
}

---

In your application.properties, specify the following: Take note that it references the full package path of the Filter.

mp.openapi.filter=org.acme.OASModelFilter

---

Contents of user.json file:

{
  "hello": "world",
  "my": "json",
  "testing": "manually adding resource JSONs as examples"
}

---

The JSON file used is located directly under resources. Of course you can change that path, but you need to update your InputStream.

---

mvn clean install

---

mvn quarkus:dev

---

Go to http://localhost:8080/q/swagger-ui/ and you will now see your user.json file contents displayed

Hopes this helps you,

References for my investigation:

https://github.com/labcabrera/rolemaster-core/blob/c68331c10ef358f6288518350c79d4868ff60d2c/src/main/java/org/labcabrera/rolemaster/core/config/OpenapiExamplesConfig.java

https://github.com/bf2fc6cc711aee1a0c2a/kafka-admin-api/blob/54496dd67edc39a81fa7c6da4c966560060c7e3e/kafka-admin/src/main/java/org/bf2/admin/kafka/admin/handlers/OASModelFilter.java

Answer 2

The below works, but as you can see I am creating the PATHS, and you still need to know what the (path/address/is) in order to create paths.

It could help you in thinking in approaching it in a different way.

If you are considering modifying the @ApiResponses/@ApiResponse annotations directly, then it wont work.

package org.acme;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;
import org.eclipse.microprofile.openapi.OASFactory;
import org.eclipse.microprofile.openapi.OASFilter;
import org.eclipse.microprofile.openapi.models.Components;
import org.eclipse.microprofile.openapi.models.OpenAPI;

import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.util.LinkedHashMap;
import java.util.Map;

import org.eclipse.microprofile.openapi.models.examples.Example;

import io.quarkus.logging.Log;

public class CustomOASFilter implements OASFilter {

    ObjectMapper objectMapper = new ObjectMapper();

    @Override
    public void filterOpenAPI(OpenAPI openAPI) {

        //openApi.getComponents() will result in NULL as we don't have any openapi.yaml file.
        Components defaultComponents = OASFactory.createComponents();
        if (openAPI.getComponents() == null) {
            openAPI.setComponents(defaultComponents);
        }

        generateExamples().forEach(openAPI.getComponents()::addExample);


        openAPI.setPaths(OASFactory.createPaths()
                                   .addPathItem(
                                           "/hello/customer", OASFactory.createPathItem()
                                                                        .GET(
                                                                                OASFactory.createOperation()
                                                                                          .operationId("hello-customer-get")
                                                                                          .summary("A simple get call")
                                                                                          .description("Getting customer information")
                                                                                          .responses(
                                                                                                  OASFactory.createAPIResponses()
                                                                                                            .addAPIResponse(
                                                                                                                    "200", OASFactory.createAPIResponse()
                                                                                                                                     .content(OASFactory.createContent()
                                                                                                                                                        .addMediaType("application/json", OASFactory.createMediaType()
                                                                                                                                                                                                    .examples(generateExamples()))))))));

    }

    Map<String, Example> generateExamples() {

        Map<String, Example> examples = new LinkedHashMap<>();

        try {

            ClassLoader loader = Thread.currentThread().getContextClassLoader();

            String userJSON = new String(loader.getResourceAsStream("user.json").readAllBytes(), StandardCharsets.UTF_8);
            String customerJson = new String(loader.getResourceAsStream("customer.json").readAllBytes(), StandardCharsets.UTF_8);

            Example userExample = OASFactory.createExample()
                                            .description("User JSON Example Description")
                                            .value(objectMapper.readValue(userJSON, ObjectNode.class));

            Example customerExample = OASFactory.createExample()
                                                .description("Customer JSON Example Description")
                                                .value(objectMapper.readValue(customerJson, ObjectNode.class));

            examples.put("userExample", userExample);
            examples.put("customerExample", customerExample);

        } catch (IOException ioException) {
            Log.error(ioException);
        }
        return examples;
    }

}

Answer 3

EDIT: This is working well in spring-boot

The above answer might work but it has too much code to put into to make it work.

Instead, you can use externalValue field to pass on the JSON file.

For example,

@ExampleObject(
  summary = "temp",
  name =
      "A 500 error",
  externalValue = "/response.json"
)

And now you can create your json file under /resources/static like below,

Swagger doc screenshot

And that's all you need. You don't need to write any manual code here.

Hope this will help you fix the issue.