Develop Reference

Spring REST Pageable / Query Parameters in Swagger

I'm trying to implement paging in my REST service.
TAKE 1:
public Page<Item> getPagedItems(Pageable pageable)
This is a known bug in SpringFox / Swagger where the Swagger page shows the wrong parameter names. Plus, I just want page & size options.
TAKE 2:
public Page<Item> getPagedItems(#RequestParam(name="page", required=true) int page, #RequestParam(name="page", required=true) int size)
This gives me the correct params, but it doesn't let me set the param descriptions or example values.
TAKE 3:
#ApiImplicitParams({
#ApiImplicitParam(name="page", value="page description", required=true, example="0", dataType="int"),
#ApiImplicitParam(name="size", value="size description", required=true, example="10", dataType="int")
})
public Page<Item> getPagedItems(int page, int size)
This has yet ANOTHER bug where example="0" doesn't work, but every other value except that one works lol. If I change the datatype to String then it'll display the 0 example value, but then it'll let you put in anything in the text box. Also tried "0 ", "0.0", "0\0", etc. Stuff like that.
If I don't set examples, then Springfox throws an exception complaining about no examples lol. The closest thing I can do is put 0 for both with both blank. Ugh. Having 0 / 10 isn't a good option since the 0 doesn't work, but the 10 does.
Any idea how to get an example of 0 to work? Spring Fox doesn't seem to be too well supported, even for open source, so no response on GitHub.
Or some other way of having an example AND description?

We created a inherited annotation and used that :
#Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE, ElementType.TYPE})
#Retention(RetentionPolicy.RUNTIME)
#Inherited
#ApiImplicitParams({
#ApiImplicitParam(name = "page", dataTypeClass = int.class,defaultValue = "0", example = "0", paramType = "query", value = "Results page you want to retrieve (0..N)"),
#ApiImplicitParam(name = "size", dataTypeClass = int.class ,example = "10", paramType = "query", value = "Number of records per page."),
#ApiImplicitParam(name = "sort", allowMultiple = true, dataTypeClass=String.class, paramType = "query", value = "Sorting criteria in the format: property(,asc|desc). "
+ "Default sort order is ascending. " + "Multiple sort criteria are supported.")
})
public #interface ApiPagingParams {
}
usage
#ApiPagingParams
#ResponseStatus(HttpStatus.OK)
#GetMapping("/entity")
ResponseEntity<Page<...>> getSurveyEntityList(#ApiIgnore("see #ApiPagingParams") #PageableDefault(page = 0, size = 10) Pageable pageable,...)

How to send object parameters in Swagger API definition?

I have the following API definition endpoint:
paths:
/pricing/reservation:
get:
tags:
- Pricing
summary: Get a reservation base price
description: Returns the pricing for a reservation
operationId: getReservationPricing
produces:
- application/json
parameters:
- name: beginDate
in: query
description: reservation begin date
required: true
type: integer
format: int64
- name: endDate
in: query
description: reservation end date
required: true
type: integer
format: int64
- in: body
name: vehicle
description: Vehicle objec
required: true
schema:
$ref: '#/definitions/Vehicle'
responses:
200:
description: successful operation
schema:
type: number
format: float
404:
description: Vehicle not found
I want to request a Vehicle object by parameter and then, with the Bitbucket integration, generate the API interface in Java. That way I can override the API controller and define the endpoint logic.
My question is, is there a way to define a generic object from Swagger definition, or do I have (as I did in above code) to define my Swagger object definition and then map it in Java?
The API generated inteface with Swagger schema:
#ApiOperation(value = "Get a reservation base price", nickname = "getReservationPricing", notes = "Returns the pricing for a reservation", response = Float.class, authorizations = {
#Authorization(value = "api_key")
}, tags={ "Pricing", })
#ApiResponses(value = {
#ApiResponse(code = 200, message = "successful operation", response = Float.class),
#ApiResponse(code = 404, message = "Vehicle not found") })
#RequestMapping(value = "/pricing/reservation",
produces = { "application/json" },
method = RequestMethod.GET)
ResponseEntity<Float> getReservationPricing(#NotNull #ApiParam(value = "reservation begin date", required = true) #Valid #RequestParam(value = "beginDate", required = true) Long beginDate,#NotNull #ApiParam(value = "reservation end date", required = true) #Valid #RequestParam(value = "endDate", required = true) Long endDate,#ApiParam(value = "Vehicle object that needs to be added to the fleet" ,required=true ) #Valid #RequestBody Vehicle vechicle);
Thanks for your help!

How to convert JSON response to Java List- Using Rest Assured for API Testing

I have a nested JSON response. JsonResponse Screenshot
I want to get the the dictionary at 0th location from the list and then get a particular element from it.
For e.g. In response, {0} and {1}, I want to get complete {0} as a result. Then from {0}, I want to extract "Id" value only.
I don't want to use the JsonPath.read(JsonResponse String, JSON Path) everytime. So looking for some simple and better alternative.
How to convert JSON response to Java List. Below is the response.
Response resp = given().header("Authorization", "Bearer "+"dwded").
accept(ContentType.JSON).
when().
get("https://example.com");
return resp;

For testing a web-API or REST endpoint, I would recommend Karate.
So it becomes simple:
* def id = response[0].Id

In the swagger editor pet example.
responses:
200:
description: "successful operation"
schema:
type: "array"
items:
$ref: "#/definitions/Pet"
A model is generated from the
Pet:
type: "object"
properties:
name:
type: "string"
example: "doggie"
This generated a java class
public class Pet {
#JsonProperty("name")
private String name = null;
The api shows a REST that returns an entity that can be shown as an array of json objects
ResponseEntity<List<Pet>> findPetsByStatus( #NotNull#ApiParam(value = "Status values that need to be considered for filter", required = true, allowableValues = "available, pending, sold") #RequestParam(value = "status", required = true) List<String> status);

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

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

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;;
}

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:

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

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> { ... }

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

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

How to extract parameters from an object to show in parameters in documentation

I have the following API endpoint:
#ApiResponses(
value = {
#ApiResponse(code = 200, message = "OK",
responseHeaders = {
#ResponseHeader(name = "X-RateLimit-Limit", description = "The defined maximum number of requests available to the consumer for this API.", response = Integer.class),
#ResponseHeader(name = "X-RateLimit-Remaining", description = "The number of calls remaining before the limit is enforced and requests are bounced.", response = Integer.class),
#ResponseHeader(name = "X-RateLimit-Reset", description = "The time, in seconds, until the limit expires and another request will be allowed in. This header will only be present if the limit is being enforced.", response = Integer.class)
}
)
}
)
#ApiOperation(httpMethod = "GET", hidden = false, nickname = "Get Network Availability in JSON", value = "Get network availability for a product", response = AvailableToPromise.class, position = 1)
#RequestMapping(value = "/{product_id}", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_VALUE)
public ResponseEntity<?> networkAvailabilityJsonResponse(
#RequestHeader HttpHeaders headers,
#PathVariable("product_id") String productId,
#Valid NetworkAvailabilityCmd cmd, //query params
BindingResult result)
throws Exception {}
}
Certain parameters, such as key are taken from the query and mapped into this object through Spring MVC.
However, in the parameters section of my endpoint in the swagger-ui, it's showing me a few odd things:
None of the variables that are in NetworkAvailabilityCmd show in this parameters list, and cmd itself shows as being located in the request body (it's actually located in the query). Is there a way to hide cmd and extract the params inside this object to show on the params list? I'd like the params list to look like this (with more params):
I'm able to do this if I use #ApiImplicitParams on the method endpoint, and write out each of the params. However, this NetworkAvailabilityCmd is used for many endpoints, and having the list of params on each endpoint is very messy. Being able to extract the variables from in the object would be far cleaner, and would prevent people from forgetting to add the entire list to new endpoints.
I imagine that it requires an annotation on NetworkAvailabilityCmd cmd, and potentially something on the variables in that class, but I can't seem to find what I'm looking for in the docs.
Thanks!

I found out that adding #ModelAttribute worked magically. This annotation is from Spring.