web-dev-qa-db-ja.com

Swaggerアノテーションを使用してSwaggerで説明と例を設定するにはどうすればよいですか？

Springブートを使用してREST AP​​Iを作成し、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が示しているものです。

enter image description here

最後に、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'

だから、質問は次のとおりです：スワッガー注釈を使用してボディパラメータの説明と例を設定する方法を知っている人はいますか？

EDIT

@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}")}))})
javaspringswaggerswagger-codegen
29
DarthRoman

Bodyオブジェクトのサンプルを生成する際にも同様の問題があります-アノテーション@Exampleおよび@ExamplePropertyはswagger 1.5.xでは理由もなく動作しません。 （1.5.16を使用）

私の現在のソリューションは次のとおりです。
use @ApiParam(example="...") for non-body objects、例：

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;;
}
11
Artem Trofimoff

実際、@ApiParamアノテーションのexampleプロパティのJava docは、これが非本体パラメーターにのみ使用されることを示しています。 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を試しましたが、どちらのバージョンもswaggerのx-examplesプロパティを使用しませんでした。

swagger-uiのコード にはx-example（非ボディパラメータに使用されるもの）の参照がいくつかありますが、x-examplesには一致しません。これは、現時点ではswagger-uiでサポートされていないようです。

この例の値を本当に必要とする場合、現在の最良の選択肢は、メソッドのシグネチャを変更し、bodyパラメーターに専用のドメインタイプを使用することです。コメントで既に述べたように、swaggerはドメインタイプの構造を自動的に取得し、swagger-uiでニース情報を出力します。

Swagger-UI 2.2.10 with domain type info

2
dpr

以下を試しましたか？

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

ごきげんよう

1
E. Bavoux

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

0
Евгений Коптюбенко