springfox: ApiResponse.examples not showing in swagger ui

Version: springfox 2.9.2, springboot 2.0.2 What kind of issue is this?: Question.
Lang: Kotlin

Examples from ApiResponse annotations are not propagated to swagger-ui. See following code:

ApiResponse(code = 200, message = "Resource created", response = String::class,
                examples = Example(value = [ExampleProperty(value = "Example text")])
        )

After spring-boot start swagger-ui present example text of response 200 as “string”. So my question is whether i am missing something or it is bug. Because my expectations were, that example text will be “Example text”. For more detailed info see used config and rest controller.

Thx for answering, V

Used config

@Configuration
@EnableSwagger2
class SwaggerConfig(@Value("\${build.version}") private val buildVersion: String) {

    @Bean
    fun api(): Docket {
        val res404 = ResponseMessageBuilder()
                .code(404)
                .message("Not found")
                .build()
        return Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.regex("^/(?!error|probe).*"))
                .build()
                .useDefaultResponseMessages(false)
                .globalResponseMessage(RequestMethod.GET, listOf(res404))
                .globalResponseMessage(RequestMethod.PUT, listOf(res404))
                .globalResponseMessage(RequestMethod.POST, listOf(res404))
                .globalResponseMessage(RequestMethod.PATCH, listOf(res404))
                .apiInfo(apiInfo)
    }

    @Bean
    fun uiConfig(): UiConfiguration {
        return UiConfigurationBuilder.builder()
                .deepLinking(true)
                .displayOperationId(false)
                .defaultModelsExpandDepth(5)
                .defaultModelExpandDepth(1)
                .defaultModelRendering(ModelRendering.EXAMPLE)
                .displayRequestDuration(false)
                .docExpansion(DocExpansion.FULL)
                .filter(false)
                .maxDisplayedTags(null)
                .operationsSorter(OperationsSorter.ALPHA)
                .showExtensions(false)
                .tagsSorter(TagsSorter.ALPHA)
                .supportedSubmitMethods(UiConfiguration.Constants.DEFAULT_SUBMIT_METHODS)
                .validatorUrl(null)
                .build()
    }
}

RestController:

@RestController
@RequestMapping(
        path = ["/path/bla"],
        consumes = [MediaType.APPLICATION_JSON_UTF8_VALUE, MediaType.APPLICATION_JSON_VALUE],
        produces = [MediaType.APPLICATION_JSON_UTF8_VALUE, MediaType.APPLICATION_JSON_VALUE]
)
class MyController {

    @ApiOperation(value = "some opeation")
    @ApiResponses(value = [
        ApiResponse(code = 200, message = "Resource created", response = String::class,
                examples = Example(value = [ExampleProperty(value = "Example text")])
        )
    ])
    fun performAction(): String {
          ....
    }
}

About this issue

Original URL
State: closed
Created 6 years ago
Reactions: 2
Comments: 29 (8 by maintainers)

Most upvoted comments

Hi,

I am facing the same issue ApiResponse.examples not showing in swagger ui. May i know when this feature will be available.

+11

prisin on Jan 17, 2019

Same problem here. Springfox 2.9.2, Kotlin 1.2.51, SpringBoot 2.0.3.RELEASE. examples parameter ignored in @ApiResponse.

mikhalchenko-alexander on Jul 25, 2018

Hey, I need this feature also. When will this be released?

ptheohar on Mar 4, 2019

Yes absolutely… Im hoping to release in the next couple weeks

dilipkrish on Apr 23, 2020

@dilipkrish Hello! Are there any updates about that issue?

ksrh on Apr 10, 2019

While trying to figure this one out, I noticed that the example response is properly returned if you give up on specifying correct media type. In other words, the example below somewhat works for me:

@PostMapping
@ApiResponses({
	@ApiResponse(code = 400, message = "Bad Request", examples = @Example({
		@ExampleProperty(mediaType = "*/*", value = "{\"status\": \"BAD_REQUEST\"}")
	}))
})
public ResponseEntity<RegistrationResource> register(@RequestBody @Valid RegistrationDTO registrationDTO) {
…
}

Tested with the 3.0.0-SNAPSHOT version of Springfox.

Edit: better yet, you can just specify the produces = "application/json" parameter in the @PostMapping annotation, and then use the same media type for @ExampleProperty. It seems that SpringFox simply doesn’t understand that @RestController specifies JSON as the output type.

ml-milan-vit on Jun 2, 2020

I used @ApiResponses(…). It worked.

@ApiResponses(value = { @ApiResponse(code = 200, message = “OK -> The user has been fetched successfully”), @ApiResponse(code = 201, message = “OK -> The user has been created successfully”), @ApiResponse(code = 202, message = “Accepted -> The user has been updated successfully”), @ApiResponse(code = 204, message = “NO CONTENT -> The user has been removed successfully”) })

You can use it at the class level or a method level.

JuanGQCadavid on Apr 7, 2020

According to this test springfox/springfox-spring-web/src/test/java/springfox/documentation/spring/web/dummy/controllers/FeatureDemonstrationService.java

Lines 291 to 307 in ac4c54e

@RequestMapping(value = “/1570”, method = RequestMethod.POST) @ApiOperation(value = “Demo using examples”) @ApiResponses(value = {@ApiResponse(code = 404, message = “User not found”), @ApiResponse( code = 405, message = “Validation exception”, examples = @io.swagger.annotations.Example( value = { @ExampleProperty( mediaType = “Example json”, value = “{"invalidField": "address"}”), @ExampleProperty( mediaType = “Example string”, value = “The first name was invalid”)}))}) public void saveUser() { //No-op } We see this output

springfox/swagger-contract-tests/src/test/resources/contract/swagger2/declaration-feature-demonstration-service.json

Lines 206 to 233 in ac4c54e

“/features/1570”: { “post”: { “consumes”: [ “application/json” ], “deprecated”: false, “operationId”: “saveUserUsingPOST_1”, “responses”: { “200”: { “description”: “OK” }, “404”: { “description”: “User not found” }, “405”: { “description”: “Validation exception”, “examples”: { “Example json”: “{"invalidField": "address"}”, “Example string”: “The first name was invalid” } } }, “summary”: “Demo using examples”, “tags”: [ “feature-demonstration-service” ] } }, Not sure, if its something with Kotlin or springboot 2.0

I see that you use @Controller in your source code. If you switch to @RestController, it doesn’t work.

tdoan2010 on Mar 14, 2019

According to this test https://github.com/springfox/springfox/blob/ac4c54ea7b2d9aa5816b1bff43de1e757cd66791/springfox-spring-web/src/test/java/springfox/documentation/spring/web/dummy/controllers/FeatureDemonstrationService.java#L291-L307

We see this output

https://github.com/springfox/springfox/blob/ac4c54ea7b2d9aa5816b1bff43de1e757cd66791/swagger-contract-tests/src/test/resources/contract/swagger2/declaration-feature-demonstration-service.json#L206-L233

Not sure, if its something with Kotlin or springboot 2.0

dilipkrish on Aug 4, 2018

Tried same code as provided in test example with controller written in Java and examples are not showing. example project https://github.com/stengvac/spring-boot-swagger2 where you see and try swagger ui if you want.

so it is possible, that problem is in spring-boot?

stengvac on Aug 9, 2018