Springfox: Add support in the models for rendering examples in operations etc.

I just stumbled about this issue. For me, it looks more than a bug than a feature, because springfox is supporting example values from the ApiModel annotation. Why is it ignoring the ApiParam example attribute? Is there a complexity that I don't understand? If not and it is just not prioritized I would give it a shot and provide a small pull request.

that would be great! :metal: Let me know if you have any questions

+1
Was there some progress on this issue by anyone so far ?
We'd love to have this feature too.

No bandwidth to do this currently. Would you perhaps like to give a shot at a PR? I'd be more than happy to help answer any questions.

Sadly I won't have time to take a look at this for now

+1

Instructions on how to do this in case someone wants to help

Hey have a look at these instructions to support a custom annotation for a parameter. Essentially we need to do a similar thing ... with a little bit more work.

1. We need to add an example property to the Parameter object
2. Add corresponding property to ParameterBuilder
3. Add logic to map the internal Parameter model to the swagger Parameter model

We need to do the same thing for Response model as well. Update the builder and the mapper

Once we do the above we can create a ParameterBuilderPlugin for the parameters and OperationBuilderPlugin plugin for response examples.

+1

+1

@dilipkrish I have a question about a similar use case.

I have a re-usable core JSON class (just id/label pairs) called BasicJSON

The JSON object used for POST/PUT/GET (call it FooJSON) has multiple fields of type BasicJSON

I don't need/want to annotate the @ApiParameter or @RequestBody of various controller methods, I simply want to provide different examples of BasicJSON for different fields on FooJSON.

The example attribute of @ApiModelProperty only allows strings. Is there a way to format the "string" value so that it gets converted into proper json by the swagger ui? I tried something like '{"id": 7, value: "Hello"}' with various versions of quoting but the UI treated them like just strings not as json objects. It seems to me that the @ExampleProperty could be useful somehow in this context as well if there is a hard-constraint on example attribute being a String.

Yeah you're right about ExampleProperty. However with all of that changing in the near future with 3.0 I don't really know if it would be worth adding support in the core product just yet only to change it pretty soon.

Thanks for the response. Is the timeline and feature set of 3.0 documented somewhere?

Its all in the issue queue... prioritized by demand :) Mostly stories tagged someday aren't really worth (my time) supporting in the core library, because there are extensibility mechanisms that already support it.

Sorry to be slow, are you referring to Springfox 3.0 or Swagger 3? For springfox, I only see 2.7.0 upcoming. In either case, will there be an avenue for me to provide more specific examples on fields via @ApiModelProperty or similar?

It can be confusing :)

1. OpenAPI is the spec (aka swagger) that has version => 2.0 (current). 3.0 has a lot of the new stuff and changes in the structure of the document.
2. Swagger-Core is the tool chain that is built on top of Open API 2.0 and JAX-RS, Jersey and a slew of other libraries and frameworks for the JVM. Currently in version => 1.5.x. For all practical purposes we don't care about this library.
3. SpringFox is the library that can generate OpenAPI documents (supports 1.2 and 2.0) for the spring ecosystem . Currently in version => 2.7.0-SNAPSHOT

So what I was implying was that since (1) is changing in the near future, its not good use of time in building something for v2.0 of (1) in Springfox (3) since it needs to be re-worked pretty soon.

Was that helpful?

Thanks for the clarity 👍

One quibble I have is that Swagger/OpenAPI version 3 is just now a release candidate so that IMO it may be a while before it has the widespread tooling support and acceptance by the community that Swagger 2 has now. Furthermore, since springfox still supports Swagger 1, I can't imagine springfox will be dropping support for swagger 2 very soon :) So the functionality I am asking about will have value even if the implementation details will vary for a swagger 2 docket vs. a swagger 3 docket.

OTOH, I realize that efforts to support OpenAPI 3.0.0 in springfox would naturally come before this kind of feature request. Much thanks for all you do with this project!

NOTE: Here Im using swagger to loosely mean OpenAPI

Actually,it is a lot easier to move from version to version of the spec, the hard work of understanding springs model is already done. The swagger1/swagger2 are just a project of the internal models that we create. i.e. We have our own model => swagger1 mapping layer == produces ==> swagger1
and same for swagger2.

Now our internal models are a little bit skewed because they used to mirror swagger 1 and we've added on to it more and more to expose newer concepts like examples.

The structure of swagger 3 is bit different from its predecessors so its Im not sure of the effort it will take to change the internal models. There are a lot of new concepts in the works like links/hypermedia, more rich schema support like allOf and anyOf, more rich example support. So I don't want to put a lot of effort into supporting/improving the models to handle examples etc. till I understand the impact of it. Really once its out there it is going to have to be supported :)

+1

Need support for example in Springfox
{ @ApiImplicitParam(example = "...") } does not work using Sprinfox.

+1

+1

+1

+1

+1

+1

+1

+1

+1

@dilipkrish You commented previously that work is prioritized from the Issues queue based on demand. There seems to be a pretty high level of interest in addressing this issue, so i was wondering if this work is still prioritized behind support OpenAPI 3.0

+1

@andrew-garland Ive not had much time recently unfortunately. That is why Im relying on help from external contributions looking-for-contributions. First priority is to get OAS 3.0 support.

+1

+1

+1

Everyone, contributions are welcome

+1

+1

+1

+1

+1

+1

+1

+1

+1

+1

+1

+1

+1

@JensSchliesser +1 for what? Its already implemented.

+1 in thanks for implementing

Is there a working example of this, as I couldn't get the example stuff working and displaying in the swagger ui, and I've tried using 2.9.0

+1 really need it

@darrellme There is an example in the docs and for scalar properties do this.

+1

+1

@dilipkrish Your example produces 'x-examples' field with object example. But 'x-examples' is not supported by SwaggerUI 3.x. Is there a working example with complex object example? Thanks

I'm not sure it is supported in the ui

@darrellme There is an example in the docs and for scalar properties do this.

@dilipkrish Would it work for RequestBody too? I do not see any example for same.
Tried using SpringFox 2.9.2, following code for reference:
@ApiParam(name = "body",value = "Request body in JSON format...",required=true, examples = @io.swagger.annotations.Example(value= @ExampleProperty( mediaType = MediaType.APPLICATION_JSON_VALUE, value = "{foo: whatever, bar: whatever2}")) ) @RequestBody String body,

I would like to display one large JSON as example value for request body and clicking on 'Try it out' application should show same in edit mode. Please refer to following URL for my expectation behavior []https://petstore.swagger.io/#/store/placeOrder
Also note that I am not passing any objects in parameters to method, it is simple 'String' type request body as I have mentioned above in my code snippet.
Please suggest.

No bandwidth to do this currently. Would you perhaps like to give a shot at a PR? I'd be more than happy to help answer any questions.

Instructions on how to do this in case someone wants to help

Hey have a look at these instructions to support a custom annotation for a parameter. Essentially we need to do a similar thing ... with a little bit more work.

1. We need to add an example property to the Parameter object
2. Add corresponding property to ParameterBuilder
3. Add logic to map the internal Parameter model to the swagger Parameter model

We need to do the same thing for Response model as well. Update the builder and the mapper

Once we do the above we can create a ParameterBuilderPlugin for the parameters and OperationBuilderPlugin plugin for response examples.
Hi, I have a problem using Swagger.My response body in controller methods has a map.
So how can I describe each field in my response body so that others can understand.
For now ,the response example is nothing, could you give a demo to achieve it?

Instructions on how to do this in case someone wants to help

Hey have a look at these instructions to support a custom annotation for a parameter. Essentially we need to do a similar thing ... with a little bit more work.

1. We need to add an example property to the Parameter object
2. Add corresponding property to ParameterBuilder
3. Add logic to map the internal Parameter model to the swagger Parameter model

We need to do the same thing for Response model as well. Update the builder and the mapper

Once we do the above we can create a ParameterBuilderPlugin for the parameters and OperationBuilderPlugin plugin for response examples.
@dilipkrish
Hi, I have a problem using Swagger.My response body in controller methods has a map.
So how can I describe each field in my response body so that others can understand.
For now ,the response example is nothing, could you give a demo to achieve it?