Provide sample value for request parameter in Swagger

swagger request body example annotation
swagger query parameter example
swagger 2.0 request body example
swagger query parameter array example
swagger response example json
swagger yaml example
swagger response list of objects
swagger array of objects

I have a method signature for a rest method in a Spring-Boot RestController that looks like this:

@RequestMapping(
        value = "/path",
        method = RequestMethod.POST,
        consumes = MediaType.APPLICATION_JSON_VALUE,
        produces = MediaType.APPLICATION_JSON_VALUE
)
@ApiImplicitParams({
        @ApiImplicitParam(
                name = "message", 
                value = "Message that is sent to the method", 
                required = true, 
                dataType = "string", 
                paramType = "body"
        )
})
public @ResponseBody String receiveMessage(@RequestBody String message) {
    // ...

    return "{\"success\": true}";
}

I would like to provide a "sample" value for the message parameter that is a JSON string (e.g. {"key" : "value"}). Does anybody know how I can do this using Swagger annotations? I tried

@ApiImplicitParams({
        @ApiImplicitParam(
                // ...
                example = "...JSON value..."
        )
})

but it didn't work. What I would like to have is a "sample value" in the documentation, that the reader can click on to have the parameter value field in the documentation filled with the given sample value. Is this possible?

Here is a screenshot of how it might look like:

Just to prevent "useless" answers: I cannot change the type of the parameter from String to some class type due to my business logic.

Unfortunately you cannot provide an sample or example value for atomic parametera (String, Number, ...).

You can only provide an example if the parameter is an object with a schema, you only have to add an example property to the property description:

properties:
  firstName:
    description: first name
    type: string
    example: John

As a last resort you could add an example value in the parameter's description (value in the ApiImplicitParam annotation).

    @ApiImplicitParam(
            name = "message", 
            value = "Message that is sent to the method. Example: value", 
            required = true, 
            dataType = "string", 
            paramType = "body"
    )

Adding Examples, A default value is what the server uses if the client does not provide the value. value: parameters: - in: query; name: status; schema: type: string; enum: [​approved, Note: the sample values you specify should match the parameter data type. Describing Parameters In Swagger, API operation parameters are defined under the parameters section in the operation definition. Each parameter has name, value type (for primitive value parameters) or schema (for request body), and optional description. Here is an example: paths: /users/{userId}: get: summary: Gets a user by ID.

For Spring Boot users, assuming you've a REST method, accepting json body, but for some reasons doesn't explicitly uses @RequestBody. Follow below steps to generate proper Swagger documentation

Update SpringFox configuration bean for additional model

@Bean
public Docket apiDocket() {
     return new Docket(DocumentationType.SWAGGER_2)
             // ...
             .additionalModels(new TypeResolver().resolve(YourRequestModel.class));
}

Update controller API for @ApiImplicitParams

@PostMapping("/your-api")
@ApiOperation(value = "brief description", notes = "Greater details come here")
@ApiImplicitParams({
   @ApiImplicitParam(paramType = "header", name = "x-locale", example = "en"),
   @ApiImplicitParam(paramType = "body", dataType = "YourRequestModel")
})
public YourResponsetModel processRequest() {
   // ...
   return null;
}

This will generate us Swagger with an optional header x-locale, and body of type YourRequestModel.

Provide sample value for request parameter in Swagger, Each parameter has name , value type (for primitive value parameters) or schema (for request body), and optional description . Here is an example: paths  Using default to specify a sample value. This is not intended use of default and can lead to unexpected behavior in some Swagger tools. Use the example or examples keyword for this purpose instead. See Adding Examples. Enum Parameters You can restrict a parameter to a fixed set of values by adding the enum to the parameter’s schema. The enum values must be of the same type as the parameter data type.

You can try this:

public MyObject myController(@ApiParam(example = "examplestring") @RequestParam("name") String name,
            @ApiParam(example = "1")@RequestParam("eventNo") int eventNo, @ApiParam(example = "2")@RequestParam("halRequestNo") int halRequestNo){

Path parameter examples for swagger · Issue #540 · apiaryio/dredd , A default value is something that the server uses if the value is not provided in the request. Schema Examples. The example key is used to provide a schema  I would like to provide a "sample" value for the message parameter that is a JSON string (e.g. {"key" : "value"}). Does anybody know how I can do this using Swagger annotations? Does anybody know how I can do this using Swagger annotations?

Step 3: Parameters (API reference tutorial), Unfortunately you cannot provide an sample or example value for atomic parametera (String, Number, ). You can only provide an example if  This article showed you a sample of how to add custom request parameters in Swagger using ASP.NET Core 3.1 and Swashbuckle.AspNetCore 5.0.0 Join Women In Tech Virtual Conference Why Join Become a member Login

Specify an Array of Strings as Body Parameters in Swagger, out how to specify an example value for a path parameter in the swagger Thank you for giving Dredd with Swagger a try and providing this  Nope – you can’t define default values for a query string request parameter. My ExamplesOperationFilter populates the “example” property of a schema object in the swagger json. Thus in order to have an “example” a parameter must have a “schema” property.

Swagger vendor extensions, Swagger UI shows the request body The Example Value shows a  Adding Examples. You can add examples to parameters, properties and objects to make OpenAPI specification of your web service clearer. Examples can be read by tools and libraries that process your API in some way. For example, an API mocking tool can use sample values to generate mock requests.

Comments
  • Why not use a data class as a parameter and document using @ApiModelProperty?