How I can refer in @ExampleObject to local resource in my project repository?

[lociko]

Q	A
Bug or feature request?	Feature request
Which Swagger-Core version?	OpenApi 3.0.0
Which Java version?
Which JAX-RS framework & version?	JAX-RS and Jackson

Hi, I want to refer in @ExampleObject to an example as a local resource. As I experienced a can refer only an URL to some hosted example. So my question is can I have in some way in @ExampleObject reference to a local resource from my project repository?

The reason is that I want to have a static HTML or PDF generated documentation from my sources (that include OpenApi annotations). And I don't want to have examples directly included in my java codebase to avoid code mess or have examples hosted somewhere.

I want to have a project structure like this:

• main
  • java
    • com.example.services
      • ExampleRestService.java
  • resources
    • documentation
      • examples
        • UserModelExample.json

I am not sure that it is the right place to put this question but maybe someone can point me to where I should do this.

Thanks!

[frantuma]

As you're mentioning an URL I assume you are referring to externalValue field of @ExampleObject annotation, mapping to corresponding spec element which allows to specify an external URL providing the example.

It is up to you how to expose such an URL, in your example I would imagine you would expose somehow your UserModelExample.json.

If instead you want to use the "inline" value field of ExampleObject, but having the source of your json in a different file, a possible way to do that is providing an implementation of OpenApiSpecFilter and defining the class name in configuration property filterClass. Alternatively you can use a ReaderListener as mentioned in https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-JAX-RS-Project-Setup-2.0.X#customising-the-swagger-definition

[lociko]

Thank you for your quick response.

I like the idea to use the ReaderListener, but it hard to write a handler for a case when I want to replace all external examples to real value. For example:

@OpenAPIDefinition
public class BasePathModifier implements ReaderListener {
    @Override
    public void beforeScan(Reader reader, OpenAPI openAPI) {}

    @Override
    public void afterScan(Reader reader, OpenAPI openAPI) {
        initExternalExamples(openAPI);
    }

    private void initExternalExamples(OpenAPI openAPI) {
        for (PathItem pathItem : openAPI.getPaths().values()) {
            for (ApiResponse apiResponse : pathItem.getGet().getResponses().values()) {
                if (apiResponse.getContent() == null) continue;

                for (MediaType mediaType : apiResponse.getContent().values()) {
                    for (Example example : mediaType.getExamples().values()) {
                        example.getExternalValue();
                        // external value contains a path to local resource
                        // get that resource and set it to values as JSON
                        example.setValue("{\"someExampleParam\": 1}");
                    }
                }
            }
        }
    }
}

Maybe I can create a listener to exact @ExampleObject annotation avoiding that code mash. Does it possible?

[slogic]

Why not just support classpath: url in ref or classpath: for value field of ExampleObject ? My example is 70 KB size )) Security requirements, you know...

[Aravinda93]

Not sure if I am bit late but was facing the similar issue found the answer here: https://stackoverflow.com/q/71687744/7584240

Hope it helps.