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

Question

我正在使用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<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; 
} 

的@ApiParam的例子属性已被我手动插入，因为代码生成被忽略YAML的一部分（这是另一个问题：为什么编辑忽略的例子部分？）。这里是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 
     } 

最后，这就是招摇是显示：

最后，在使用的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' 

所以，问题是： 有没有人知道我可以使用Swagger注释来设置描述和身体参数的示例？

编辑

我已经取得了变更使用，而不是@ApiParam @ApiImplicitParam说明，但例如，至今下落不明：

@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

你试过以下？

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

有一个愉快的一天