How to set description and example in Swagger using Swagger annotations?

Question

I create REST Api using Spring boot and automatically generate swagger documentation in controllers using swagger codegen. However, I cannot set a description and an example for a parameter of type String in a POST request. Here is the mi code:

import io.swagger.annotations.*; @Api(value = "transaction", tags = {"transaction"}) @FunctionalInterface public interface ITransactionsApi { @ApiOperation(value = "Places a new transaction on the system.", notes = "Creates a new transaction in the system. See the schema of the Transaction parameter for more information ", tags={ "transaction", }) @ApiResponses(value = { @ApiResponse(code = 200, message = "Another transaction with the same messageId already exists in the system. No transaction was created."), @ApiResponse(code = 201, message = "The transaction has been correctly created in the system"), @ApiResponse(code = 400, message = "The transaction schema is invalid and therefore the transaction has not been created.", response = String.class), @ApiResponse(code = 415, message = "The content type is unsupported"), @ApiResponse(code = 500, message = "An unexpected error has occurred. The error has been logged and is being investigated.") }) @RequestMapping(value = "/transaction", produces = { "text/plain" }, consumes = { "application/json" }, method = RequestMethod.POST) ResponseEntity<Void> createTransaction( @ApiParam( value = "A JSON value representing a transaction. An example of the expected schema can be found down here. The fields marked with an * means that they are required." , example = "{foo: whatever, bar: whatever2}") @Valid @RequestBody String kambiTransaction) throws InvalidTransactionException; } 

The @ApiParam example property was manually inserted by me because codegen ignored this part of yaml (This is another question: why does the editor ignore part of the example?). Here is the part of Yamla:

 paths: /transaction: post: tags: - transaction summary: Place a new transaction on the system. description: > Creates a new transaction in the system. See the schema of the Transaction parameter for more information operationId: createTransaction parameters: - $ref: '#/parameters/transaction' consumes: - application/json produces: - text/plain responses: '200': description: Another transaction with the same messageId already exists in the system. No transaction was created. '201': description: The transaction has been correctly created in the system '400': description: The transaction schema is invalid and therefore the transaction has not been created. schema: type: string description: error message explaining why the request is a bad request. '415': description: The content type is unsupported '500': $ref: '#/responses/Standard500ErrorResponse' parameters: transaction: name: kambiTransaction in: body required: true description: A JSON value representing a kambi transaction. An example of the expected schema can be found down here. The fields marked with an * means that they are required. schema: type: string example: { foo*: whatever, bar: whatever2 } 

And finally, this is what swagger shows:

Finally, the dependencies used in build.gradle are as follows:

 compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.7.0' compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.7.0' 

So the question is: does anyone know how I can establish a description and an example of a body parameter using swagger annotations?

EDIT

I managed to change the description using @ApiImplicitParam instead of @ApiParam, but the example is still missing:

 @ApiImplicitParams({ @ApiImplicitParam( name = "kambiTransaction", value = "A JSON value representing a transaction. An example of the expected schema can be found down here. The fields marked with * means that they are required. See the schema of KambiTransaction for more information.", required = true, dataType = "String", paramType = "body", examples = @Example(value = {@ExampleProperty(mediaType = "application/json", value = "{foo: whatever, bar: whatever2}")}))}) 

Answer 1

I have a similar problem with generating examples for body objects - the @Example and @ExampleProperty just don't work for no reason in swagger 1.5.x. (I am using 1.5.16)

My current solution:
use @ApiParam(example="...") for objects not related to the body , for example:

 public void post(@PathParam("userId") @ApiParam(value = "userId", example = "4100003") Integer userId) {} 

for body objects , create a new class and annotate the fields using @ApiModelProperty(value = " ", example = " ") , for example:

 @ApiModel(subTypes = {BalanceUpdate.class, UserMessage.class}) class PushRequest { @ApiModelProperty(value = "status", example = "push") private final String status;; } 

Answer 2

In fact, the Java document for the example @ApiParam annotation @ApiParam claims that it should be used exclusively for non-body parameters. Where the examples property can be used for body parameters.

I checked this annotation

 @ApiParam( value = "A JSON value representing a transaction. An example of the expected schema can be found down here. The fields marked with an * means that they are required.", examples = @Example(value = @ExampleProperty( mediaType = MediaType.APPLICATION_JSON, value = "{foo: whatever, bar: whatever2}" ) ) ) 

which led to the creation of the following swagger for the corresponding method:

 /transaction: post: ... parameters: ... - in: "body" name: "body" description: "A JSON value representing a transaction. An example of the expected\ \ schema can be found down here. The fields marked with an * means that\ \ they are required." required: false schema: type: "string" x-examples: application/json: "{foo: whatever, bar: whatever2}" 

However, this value does not seem to be perceived by Swagger-UI. I tried version 2.2.10 and the latest version 3.17.4, but none of the versions used the x-examples property from swagger.

The swagger-ui code has some references to x-example (the one used for non-body parameters), but there is no match for x-examples . That is, at the moment this is not supported by swagger-ui.

If you really need the values ​​of this example to be present, you are best off changing the signature of the method and using a dedicated domain type for the body parameter. As already noted in the comments, swagger will automatically determine the structure of the domain type and display nice information in swagger-ui:

Answer 3

Have you tried the following?

 @ApiModelProperty( value = "A JSON value representing a transaction. An example of the expected schema can be found down here. The fields marked with an * means that they are required.", example = "{foo: whatever, bar: whatever2}") 

A good day

Answer 4

If you use Swagger 2.9.2, the examples do not work there. These annotations are ignored.

 protected Map<String, Response> mapResponseMessages(Set<ResponseMessage> from) { Map<String, Response> responses = newTreeMap(); for (ResponseMessage responseMessage : from) { Property responseProperty; ModelReference modelRef = responseMessage.getResponseModel(); responseProperty = modelRefToProperty(modelRef); Response response = new Response() .description(responseMessage.getMessage()) .schema(responseProperty); **response.setExamples(Maps.<String, Object>newHashMap());** response.setHeaders(transformEntries(responseMessage.getHeaders(), toPropertyEntry())); Map<String, Object> extensions = new VendorExtensionsMapper() .mapExtensions(responseMessage.getVendorExtensions()); response.getVendorExtensions().putAll(extensions); responses.put(String.valueOf(responseMessage.getCode()), response); } return responses; } 

Try using swagger 3.0.0-Snapshot. You need to change the maven dependencies as follows:

 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>3.0.0-SNAPSHOT</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>3.0.0-SNAPSHOT</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-spring-webmvc</artifactId> <version>3.0.0-SNAPSHOT</version> </dependency> 

and change the annotation in your Swagger configuration file as follows: @ EnableSwagger2WebMvc