如何使用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的示例属性已由我手动插入,因为codegen忽略了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
        }

最后,这是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'

所以,问题是: 有人知道如何使用swagger注释设置描述和身体参数的示例吗？

编辑

我已经实现了使用@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}")}))})

Answer 1

我在为body对象生成示例时遇到了类似的问题 - 注释@Example并且@ExampleProperty在swagger 1.5.x中根本无法正常工作.(我用1.5.16)

我目前的解决办法是:
使用@ApiParam(example="...")用于非人体的物体,如:

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

对于body对象创建新类和注释字段@ApiModelProperty(value = " ", example = " "),例如:

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

Answer 2

实际上，注释example属性的 java 文档@ApiParam指出，这仅用于非主体参数。该examples属性可用于身体参数。

我测试了这个注释

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

这导致为相应的方法生成以下招摇：

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

然而，这个值似乎没有被 swagger-ui 获取。我尝试了 2.2.10 版和最新的 3.17.4 版，但两个版本都没有使用x-examplesswagger的属性。

在swagger-uix-example的代码中有一些参考（用于非主体参数的）但没有匹配的x-examples. 也就是说，目前 swagger-ui 似乎不支持这一点。

如果您确实需要出现此示例值，目前您最好的选择似乎是更改方法的签名并为 body 参数使用专用域类型。正如评论中所述，swagger 将自动获取域类型的结构并在 swagger-ui 中打印一些不错的信息：

Answer 3

您是否尝试过以下方法？

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

祝你今天过得愉快