Как настроить плагин Gradle Gradle Open-API или спецификацию OpenApi YAML, чтобы отобразить правильную документацию насл ⇐ JAVA

[Anonymous]

У меня есть следующая спецификация yaml:

Код: Выделить всё

openapi: 3.0.0
info:
title: Products API
description: API for managing animals
version: '1.1'
servers:
- url: http://localhost:8081
description: Local development server

paths:
/test:
get:
tags:
- GetAnimal
operationId: getAnimal
summary: Test endpoint
description: Returns either a Dog or a Cat object.
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Animal'

components:
schemas:
Animal:
oneOf:
- $ref: '#/components/schemas/Dog'
- $ref: '#/components/schemas/Cat'
discriminator:
propertyName: type
mapping:
Dog: '#/components/schemas/Dog'
Cat: '#/components/schemas/Cat'
Dog:
type: object
properties:
type:
type: string
default: "Dog"
name:
type: string
description: The name of the dog.
age:
type: integer
description: The age of the dog in years.
required:
- type
- name
- age
Cat:
type: object
properties:
type:
type: string
default: "Cat"
name:
type: string
description: The name of the cat.
color:
type: string
description: The color of the cat's fur.
required:
- type
- name
- color
< /code>
После конфигурации плагина Gradle Gradle Open-API: < /p>
plugins {
id 'org.openapi.generator' version '7.0.0'
}
openApiGenerate {
generatorName = "spring"
inputSpec = "$projectDir/src/main/resources/open-api-specs/animals.yaml"
outputDir = "$buildDir/generated"
apiPackage = "com.example.animals.api"
modelPackage = "com.example.animals.models"

configOptions = [
documentationProvider : "springdoc",
library              : "spring-cloud",
useOneOfInterfaces   : "true",
interfaceOnly        : "true",
skipDefaultInterface : "true",
useBeanValidation    : "false",
exceptionHandler     : "false",
useTags              : "true"
]
}
sourceSets {
main {
java {
srcDirs += "$buildDir/generated/src/main/java"
}
}
}
< /code>
Он генерирует интерфейс для конечной точки с документацией и моделями: < /p>
@Generated(value = "org.openapitools.codegen.languages.SpringCodegen", date = "2025-01-26T13:13:51.451530200+02:00[Europe/Riga]")
@Tag(name = "GetAnimal", description = "the GetAnimal API")
public interface GetAnimalApi {

/**
* GET /test : Test endpoint
* Returns either a Dog or a Cat object.
*
* @return Successful response (status code 200)
*/
@Operation(
operationId = "getAnimal",
summary = "Test endpoint",
description = "Returns either a Dog or a Cat object.",
tags = { "GetAnimal" },
responses = {
@ApiResponse(responseCode = "200", description = "Successful response", content = {
@Content(mediaType = "application/json", schema = @Schema(implementation = Animal.class))
})
}
)
@RequestMapping(
method = RequestMethod.GET,
value = "/test",
produces = { "application/json" }
)
ResponseEntity  getAnimal();
}
@JsonIgnoreProperties(
value = "type", // ignore manually set type, it will be automatically generated by Jackson during serialization
allowSetters = true // allows the type to be set during deserialization
)
@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.PROPERTY, property = "type", visible = true)
@JsonSubTypes({
@JsonSubTypes.Type(value = Cat.class, name = "Cat"),
@JsonSubTypes.Type(value = Dog.class, name = "Dog")
})

@Generated(value = "org.openapitools.codegen.languages.SpringCodegen", date = "2025-01-26T13:35:37.635898900+02:00[Europe/Riga]")
public interface Animal {
public String getType();
}
@Generated(value = "org.openapitools.codegen.languages.SpringCodegen", date = "2025-01-26T13:35:37.635898900+02:00[Europe/Riga]")
public class Dog implements Animal {
private String type = "Dog";
private String name;
private Integer age;

public Dog() {
super();
}
//constructors and other things ...
}
// And Cat similarly

Реализованный интерфейс:

Код: Выделить всё

@RestController
class AnimalsController : GetAnimalApi {
override fun getAnimal(): ResponseEntity {
val cat = Cat().name("Buddy").type("Cat").color("Black")
return ResponseEntity.ok(cat)
}
}

и в swagger-ui это приводит к следующему виду:

но я хотел увидеть что-то вроде этого

и это достижимо с помощью конечной точки, документированной вручную:

Код: Выделить всё

@RestController
class AnimalsController : GetAnimalApi {
override fun getAnimal(): ResponseEntity {
val cat = Cat().name("Buddy").type("Cat").color("Black")
return ResponseEntity.ok(cat)
}

@GetMapping("/animals")
@Operation(
responses = [ApiResponse(content = [
Content(schema = Schema(oneOf = [Dog::class, Cat::class]))
])]
)
fun animals(): Animal {
return Dog().name("Buddy").age(2)
}
}

Можно ли настроить спецификацию openapi или плагин open-api-generator, чтобы добиться того же, что я делаю вручную?


Подробнее здесь: https://stackoverflow.com/questions/793 ... cification