Как установить описание и пример в Swagger с помощью аннотаций Swagger?

Ответ 1

У меня похожая проблема с генерацией примеров для объектов тела - аннотации @Example и @ExampleProperty просто не работают без причины в swagger 1.5.x. (Я использую 1.5.16)

Мое текущее решение:
используйте @ApiParam(example="...") для объектов, не связанных с телом, например:

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

для объектов тела создайте новый класс и аннотируйте поля с помощью @ApiModelProperty(value = " ", example = " "), например:

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

Ответ 2

На самом деле документ Java для example свойства аннотации @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-examples из swagger.

В коде swagger-ui есть некоторые ссылки на x-example (тот, который используется для параметров, не связанных с телом), но нет совпадения для x-examples. То есть, на данный момент это не поддерживается swagger-ui.

Если вам действительно нужно, чтобы значения этого примера присутствовали, вам лучше всего изменить подпись метода и использовать выделенный тип домена для параметра body. Как уже отмечалось в комментариях, swagger автоматически определит структуру типа домена и выведет приятную информацию в swagger-ui:

Ответ 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}")

Хороший день

Ответ 4

Если вы используете Swagger 2.9.2, примеры там не работают. Эти аннотации игнорируются

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

Попробуйте использовать swagger 3.0.0-Snapshot. Вам нужно изменить зависимости maven следующим образом:

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

и измените аннотацию в вашем конфигурационном файле Swagger следующим образом: @EnableSwagger2WebMvc