swagger java 注释,如何使用Swagger注释在Swagger中设置描述和示例？

我正在使用Spring启动创建REST Api，并使用swagger codegen在控制器中自动生成swagger文档 . 但是，我无法在POST请求中为String类型的参数设置描述和示例 . 这是mi代码：

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 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?). 这是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

}

最后，这是swagger所展示的：

最后，build.gradle中使用的依赖项如下：

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: 有人知道如何使用swagger注释设置描述和身体参数的示例吗？

EDIT

我已经实现了使用@ApiImplicitParam而不是@ApiParam更改描述，但仍然缺少示例：

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