Support relative path in @ExampleObject

[membersound]

Having a file in /src/main/resources/static/swagger/example.json. Placed inside /static because spring can expose those to the web.

It should be possible to reference the file relative to the application itself. Eg as follows:

@Operation(responses = @ApiResponse(content = @Content(examples = @ExampleObject(externalValue = "swagger/example.json")))

But even if I can access the resource via locahost:8080/swagger/example.json, when adding the url to @ExampleObject it is still not resolved:

@Operation(responses = @ApiResponse(content = @Content(examples = @ExampleObject(externalValue = "locahost:8080/swagger/example.json")))

[springdoc]

Hi,

Tested with springdoc-openapi: 1.1.15.
In order to add the examples reference, in the generated yaml/json documentation, you need to add the name of the ExampleObject:

responses= @ApiResponse(content = @Content(examples = @ExampleObject(name = "toto", externalValue = "http://localhost:8080/test/example.json")))

Displaying the example on the swagger-ui, is not a springdoc-openapi issue, but depends on a pending issue on swagger-ui side:

• Example.externalValue is not displayed swagger-api/swagger-ui#5433

[Aravinda93]

@bnasslahsen

Hello, Can you please let me know if the issue has been fixed or if there is a work-around for the same?

I am also facing the same issue where if I add the path to the file then the contents from the are not displayed within SwaggerUI. I tried using the ref and externalValue but nothing seems to work: I do not wish do provide the complete URL in my code such as "http://localhost:8080/resources/Example1.json"because the URL may change during the deployment. so wondering if there is any other way.

@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/Example1.json"
                @ExampleObject(name = "Example-2",
                        description = "Example-2 for InputTemplate.",
                        ref = "#/resources/Example1.json") //externalValue = "#/resources/Example1.json"
        }))

@bnasslahsen Can you please let me know if the issue has been fixed or if there is an work-around for the same?

[Aravinda93]

Posting the answer here as it can be useful to someone else in the future:

I was able to find a work-around based on this answer: https://stackoverflow.com/a/71699253/7584240

[PatrikScully]

@bnasslahsen I tried the following in my Spring Boot v2.6.6, Spring v5.3.18 project with springdoc-openapi-ui 1.6.7 and it not worked with the request body example. I put this annotation on a @PostMapping method:

@Operation(summary = "Operation Summary",
           requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody(
                   content = @Content(examples = @ExampleObject(name = "Example name", externalValue = "http://localhost:8080/response.json"))
           )
)

The swagger shows the @ExampleObject name and a description with the name's value, but the example value is the default Swagger generated value and not the example json file content.

The response json is in the resource/static folder, I can access it successfully via web browser. Maybe is it a bug? Is it only works with absolute URL?

[wenwangctl]

experience the same issue. would like to know if there is a solution to this. spring boot v2.6.7 and springdoc 1.6.7. externalValue does not populate swagger payload.

[gitkidmk]

I'm facing same issue and i got an idea from springdoc-openapi project.

In this project, it create example entry(http500Example) and add Example through openApiCustomiser

actually, this code represent ref in setValue but i put json file in Example object

here is my code

package com.semtax.application.config.swagger.exampleObject;

import io.swagger.v3.oas.models.examples.Example;
import org.json.simple.JSONObject;
import org.json.simple.parser.JSONParser;
import org.json.simple.parser.ParseException;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.core.io.Resource;
import org.springframework.stereotype.Component;

import java.io.IOException;
import java.io.InputStreamReader;
import java.util.*;

@Component
public class SwaggerExampleObject {

    @Value("classpath:/swagger/login.json")
    Resource loginResource;

    @Bean
    public Map.Entry<String, List<Example>> loginExample() throws IOException, ParseException, IllegalAccessError {

        JSONObject json = (JSONObject) new JSONParser().parse(new InputStreamReader(loginResource.getInputStream(), "UTF-8"));

        List<Example> ExampleList = new ArrayList<>();
        AbstractMap.SimpleEntry<String, List<Example>> loginExampleMap = new AbstractMap.SimpleEntry<>("login", null);

        for (Object s : json.keySet()){
            Example example = new Example();
            example.setValue(json.get(s));
            example.setDescription(s.toString());
            ExampleList.add(example);
        }
        loginExampleMap.setValue(ExampleList);

        return loginExampleMap;
    }
}

package com.semtax.application.config.swagger;

@OpenAPIDefinition(
        info = @Info(title = "API 명세서",
                version = "v1"))
@Configuration
@RequiredArgsConstructor
public class Swagger2Config {

    @Autowired
    SwaggerExampleObject swaggerExampleObject;

    @Bean
    public OpenApiCustomiser openApiCustomiser(Collection<Entry<String, List<Example>>> examples) {
        return openAPI -> {
            examples.forEach(example -> {
                for(Example e : example.getValue()){
                    openAPI.getComponents().addExamples(e.getDescription(), e);
                }
            });
        };
    }

}

@ApiResponse(content = @Content(examples = @ExampleObject(name = "200", ref = "#/components/examples/login200")))