스웨거 주석이 있는 스웨거에서 설명과 예제를 설정하려면 어떻게 해야 합니까?

스웨거 주석이 있는 스웨거에서 설명과 예제를 설정하려면 어떻게 해야 합니까?

저는 Spring boot을 사용하여 REST API를 만들고 있으며, Swagger codegen을 사용하여 컨트롤러에서 Swagger 문서를 자동 생성하고 있습니다.그러나 POST 요청에서 String 유형의 파라미터에 대한 설명과 예제를 설정할 수 없습니다.다음은 마이크로코드입니다.

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

코드젠이 yaml의 해당 부분을 무시했기 때문에 @ApiParam의 예제 속성은 제가 수동으로 삽입했습니다(이것은 또 다른 질문입니다: 편집자가 예제 부분을 무시하는 이유는 무엇입니까?).다음은 얌의 일부입니다.

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'

자, 질문은: 제가 스웨거 주석을 사용하여 본문 매개변수의 설명과 예제를 어떻게 설정할 수 있는지 아는 사람이 있습니까?

편집

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

본문 개체에 대한 예제 생성 - 주석과 유사한 문제가 있습니다.@Example그리고.@ExampleProperty스웨거 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;;
}

사실 자바 문서는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}"

그러나 이 값은 스웨거-의에 의해 채택되지 않은 것 같습니다.버전 2.2.10과 최신 버전 3.17.4를 시도했지만 두 버전 모두 사용하지 않았습니다.x-examples허풍쟁이의 속성

에 대한 몇 가지 참조가 있습니다.x-example(비보디 매개변수에 사용되는 것) 스웨거-의 코드에 있지만 일치하지 않습니다.x-examples그것은 현재 이것이 스웨거-의에 의해 지지되는 것 같지 않다는 것입니다.

이 예제 값이 필요한 경우 현재 메서드의 서명을 변경하고 본문 매개 변수에 전용 도메인 유형을 사용하는 것이 최선의 방법인 것 같습니다.댓글에 명시된 대로 이미 스웨거는 도메인 유형의 구조를 자동으로 선택하고 스웨거-의로 몇 가지 좋은 정보를 인쇄합니다.

다음을 시도해 보셨습니까?

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

좋은 하루 되세요.

스웨거 3.0.0을 사용하여 나머지 방법을 시도합니다.

@Operation(
        summary = "Finds a person",
        description = "Finds a person by their Id.",
        tags = { "People" },
        responses = {
            @ApiResponse(
                description = "Success",
                responseCode = "200",
                content = @Content(mediaType = "application/json", schema = @Schema(implementation = Person.class))
            ),
            @ApiResponse(description = "Not found", responseCode = "404", content = @Content),
            @ApiResponse(description = "Internal error", responseCode = "500", content = @Content)
        }
    )

Swagger.v3 Kotlin/Micronaut 예:

@Post("/get-list")
fun getList(
        @RequestBody(description = "Get list of ...",
                content = [Content(
                        mediaType = "application/json",
                        schema = Schema(implementation = RequestDTO::class),
                        examples = [ExampleObject(value = """
                            {
                                "pagination": {
                                    "page": 0,
                                    "perPage": 10
                                },
                                "filter": {
                                    "property_1": "string",
                                    "property_2": "string"
                                },
                                "sort": {
                                    "field": "property_1",
                                    "order": "DESC"
                                }
                            }
                        """)]
                )]) @Body request: RequestDTO): Response<SomeDTO> { ... }

스웨거 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을 사용해 보십시오.다음과 같이 메이븐 종속성을 변경해야 합니다.

<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

언급URL : https://stackoverflow.com/questions/46584658/how-can-i-set-a-description-and-an-example-in-swagger-with-swagger-annotations