Блог

Я использую swagger-maven-plugin для генерации файлов YAML и JSON при компиляции следующим образом:

    <plugin>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <version>2.1.7</version>
    <configuration>
      <outputFileName>openapi</outputFileName>
      <outputPath>${project.build.directory}/openapi</outputPath>
      <outputFormat>JSONANDYAML</outputFormat>
      <resourcePackages>
        <package>mypackage.rest</package>
      </resourcePackages>
      <prettyPrint>true</prettyPrint>
    </configuration>
    <executions>
      <execution>
        <phase>compile</phase>
        <goals>
          <goal>resolve</goal>
        </goals>
      </execution>
    </executions>
  </plugin>
 

Оба файла генерируются, но «ответы» выполняются по умолчанию:

 "/transactions/{id}" : {
  "get" : {
    "operationId" : "getSingleTransaction",
    "parameters" : [ {
      "name" : "id",
      "in" : "path",
      "required" : true,
      "schema" : {
        "type" : "string"
      }
    } ],
    "responses" : {
      "default" : {
        "description" : "default response",
        "content" : {
          "application/vnd.oracle.resource json;type=singular" : { }
        }
      }
    }
  }
},
 

Однако в файле класса Java он помечен ключевым словом @ApiResponse:

 @GET
@Operation(summary = "Get collection of Transactions for the given transactionId",
        description = "Get collection of Transactions for the given transactionId")
@APIResponse(description = "A list of TransactionDto",
        content = @Content(mediaType = APPLICATION_JSON,
                schema = @Schema(type = ARRAY, implementation = TransactionDto.class)))
@Consumes(APPLICATION_JSON)
@Produces(COLLECTION)
public Response getApprovalTasksForTransactionId(
        @PathParam("transactionId") TransactionId transactionId) {

    ...
}
 

Обратите внимание, что ‘ProductsDto’ является частью ApiResponse, но в определении YAML он используется по умолчанию.

Чего мне может не хватать, чтобы правильно сопоставить ответ и схему типов ответов?

Я выяснил, что мои аннотации в файле Java были импортированы из:

 import org.eclipse.microprofile.openapi.annotations
 

И выяснил, что swagger-maven-plugin нуждается в следующих аннотациях
:

 import io.swagger.v3.oas.annotations