How can I set a description and an example in Swagger with Swagger annotations?

Question

I am creating a REST Api using Spring boot, and auto generating the swagger documentation in controllers using swagger codegen. However, I am not able to set a description and example for a parameter of type String in a POST request. Here is 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 example property of the @ApiParam has been manually inserted by me, because the codegen was ignoring that part of the yaml (That is another question: why is the editor ignoring the example part?). Here is part of the yaml:

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 is showing:

Finally, the dependencies used in build.gradle are the following ones:

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

So, Question is: Does anybody know how I can set the description and an example of a body parameter using swagger annotations?

EDIT

I've achieved to change the description using @ApiImplicitParam instead of @ApiParam, but 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}")}))})

In your example you say `kambiTransaction` is of type `String`, but your method consumes `application/json`. That is you want to sent a plain text string (that contains JSON - as shown in the example value) wrapped in JSON? Why don't you create a domain class for `kambiTransaction`. Swagger will automatically print the class' structure as JSON example. — dpr, Jul 16 '18 at 15:41
I would second @dpr. The right way would be to build a model class and use annotation [ApiModel](https://github.com/swagger-api/swagger-core/wiki/annotations#apimodel) on the class and [ApiModelProperty](https://github.com/swagger-api/swagger-core/wiki/annotations#apimodelproperty) on the fields. ApiModelProperty accepts value and example parameters. — Abinash, Jul 16 '18 at 19:41

score 39 · Answer 1 · edited Oct 31 '18 at 13:21

I have similar issue with generating examples for body objects - annotation @Example and @ExampleProperty simply doesn't work for no reason in swagger 1.5.x. (I use 1.5.16)

My current solution is:
use @ApiParam(example="...") for non-body objects, e.g.:

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

for body objects create new class and annotate fields with @ApiModelProperty(value = " ", example = " "), e.g.:

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

score 12 · Answer 2 · answered Jul 17 '18 at 17:29

Actually the java doc for the example property of the @ApiParam annotation states that this is exclusively to be used for non-body parameters. Where the examples property may be used for body parameters.

I tested 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 resulted in the following swagger to be generated 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 doesn't seem to be picked up by swagger-ui. I tried version 2.2.10 and the latest 3.17.4, but neither version used the x-examples property of the swagger.

There are some references for x-example (the one used for non-body parameters) in the code of swagger-ui but no match for x-examples. That is this doesn't seem to be supported by swagger-ui at the moment.

If you really need this example values to be present, your best option currently seems to be to change your method's signature and use a dedicated domain type for the body parameter. As stated in the comments already swagger will automatically pick up the structure of the domain type and print some nice information in swagger-ui:

Is there any way to add the resources file content to the `@ExampleObject`? I am trying to add the `@ExampleObject` from the `resources file` using `ref` but its not working for some reason. I have posted my question: https://stackoverflow.com/q/71616547/7584240 — BATMAN_2008, Mar 30 '22 at 20:33

score 5 · Answer 3 · answered Nov 06 '17 at 16:29

5

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}")

Have a nice day

answered Nov 06 '17 at 16:29

E. Bavoux

535
1
4
11

2

Works perfectly, but only for the primitive types. – VadymVL Mar 23 '19 at 20:04
Is there any way to add the resources file content to the `@ExampleObject`? I am trying to add the `@ExampleObject` from the `resources file` using `ref` but its not working for some reason. I have posted my question: https://stackoverflow.com/q/71616547/7584240 – BATMAN_2008 Mar 30 '22 at 20:33

score 3 · Answer 4 · answered Dec 08 '21 at 03:14

Using swagger 3.0.0 try this over the rest method

@Operation(
        summary = "Finds a person",
        description = "Finds a person by their Id.",
        tags = { "People" },
        responses = {
            @ApiResponse(
                description = "Success",
                responseCode = "200",
                content = @Content(mediaType = "application/json", schema = @Schema(implementation = Person.class))
            ),
            @ApiResponse(description = "Not found", responseCode = "404", content = @Content),
            @ApiResponse(description = "Internal error", responseCode = "500", content = @Content)
        }
    )

score 1 · Answer 5 · answered Feb 23 '21 at 15:07

Swagger.v3 Kotlin/Micronaut example:

@Post("/get-list")
fun getList(
        @RequestBody(description = "Get list of ...",
                content = [Content(
                        mediaType = "application/json",
                        schema = Schema(implementation = RequestDTO::class),
                        examples = [ExampleObject(value = """
                            {
                                "pagination": {
                                    "page": 0,
                                    "perPage": 10
                                },
                                "filter": {
                                    "property_1": "string",
                                    "property_2": "string"
                                },
                                "sort": {
                                    "field": "property_1",
                                    "order": "DESC"
                                }
                            }
                        """)]
                )]) @Body request: RequestDTO): Response<SomeDTO> { ... }

score 0 · Answer 6 · answered Apr 26 '19 at 14:56

If you are using swagger 2.9.2 then Examples are not working 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 maven dependencies like this:

<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 annotation on your Swagger config file to this: @EnableSwagger2WebMvc

Still ignores examples/value in @ApiParam( value = "A JSON value", examples = @Example(value = @ExampleProperty(mediaType = MediaType.APPLICATION_JSON, value = "{foo: whatever, bar: whatever2}"))) — isobretatel, Feb 14 '20 at 19:15

How can I set a description and an example in Swagger with Swagger annotations?

6 Answers6

Linked