如何使用 Swagger 注释在 Swagger 中设置描述和示例? [英] How can I set a description and an example in Swagger with Swagger annotations?

问题描述

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

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

@ApiParam 的 example 属性是我手动插入的，因为 codegen 忽略了 yaml 的那部分(这是另一个问题:为什么编辑器忽略了 example 部分?). 这是yaml的一部分:

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
        }

最后，这就是 swagger 所展示的:

And finally, this is what swagger is showing:

最后，build.gradle中用到的依赖如下:

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'

所以，问题是:有谁知道我如何使用 swagger 注释来设置 body 参数的描述和示例?

So, Question is: Does anybody know how I can set the description and an example of a body parameter using swagger annotations?

编辑

我已经使用@ApiImplicitParam 而不是@ApiParam 来更改描述，但是仍然缺少示例:

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

推荐答案

我在为 body 对象生成示例时遇到了类似的问题 - 注释 @Example 和 @ExampleProperty 根本没有在 swagger 1.5.x 中不能无缘无故地工作.(我用的是 1.5.16)

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)

我目前的解决方案是:
将 @ApiParam(example="...") 用于非实体对象，例如:

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

为 body 对象创建新类并使用 @ApiModelProperty(value = " ", example = " ") 注释字段，例如:

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

这篇关于如何使用 Swagger 注释在 Swagger 中设置描述和示例?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！