Crear swagger-ui a partir de open-api.yml
Estoy intentando generar interfaces a partir de una especificación de Open-API y tengo un complemento de Gradle:
implementation(
"org.springdoc:springdoc-openapi-ui:1.5.12",
"org.openapitools:openapi-generator-gradle-plugin:5.3.0"
)
Defino el archivo de API como:
def apiFile = "$rootDir/src/main/resources/openapi/api.yml"
La tarea buildOpenApi
se configura de la siguiente manera:
task buildOpenApi(type: GenerateTask) {
generatorName = "spring"
inputSpec = apiFile
outputDir = "$buildDir/generated"
groupId = "$project.group"
id = "$project.name-java-client"
version = "$project.version"
apiPackage = "com.example.my.api"
modelPackage = "com.example.my.model"
configOptions = [
interfaceOnly: "true",
openApiNullable: "false",
skipDefaultInterface: "true"
]
globalProperties = [
apis: "",
models: ""
]
enablePostProcessFile = true
skipOverwrite = false
}
La dependencia compileJava
se basa en buildOpenApi
:
compileJava.dependsOn(buildOpenApi)
sourceSets.main.java.srcDirs = ['build/generated/src','src/main/java']
Tengo un archivo api.yml
ubicado en src/main/resources/openapi/api.yml
. Cuando ejecuto ./gradlew clean compileJava
, se generan las interfaces correctas en el directorio de compilación, por lo que puedo implementarlas. Pero cuando inicio mi aplicación y voy a http://localhost:8080/swagger-ui.html`, veo que Swagger se genera automáticamente a partir de mis clases de controlador, pero no desde el archivo
api.yml`, es decir, no tiene descripciones, ejemplos, etc.
¿Cómo puedo hacer que Swagger se construya a partir de mi archivo api.yml
y no desde el código fuente del controlador?
davy.ai
Para generar Swagger a partir de su archivo
api.yml
, necesita agregar cierta configuración a su aplicación Spring.En primer lugar, debe tener la dependencia swagger-ui en su proyecto. Puede agregar esto a su archivo gradle:
Luego, debe configurar su aplicación Spring para generar la documentación de Swagger a partir de su archivo
api.yml
. Puede hacerlo agregando la anotación@EnableSwagger2
o@EnableSwagger2WebMvc
a su clase de configuración de Spring.Esta clase de configuración generará la documentación de Swagger a partir de las clases controladoras. Para generar la documentación a partir de su archivo
api.yml
, debe modificar la configuración de la siguiente manera:Esta configuración analizará el archivo
api.yml
y lo convertirá del formato YAML al formato JSON. Luego, utilizará el JSON convertido para construir el objeto OpenAPI, que se utilizará para generar la documentación de Swagger.Una vez que agregue esta configuración a su aplicación Spring, puede iniciar su aplicación e ir a
http://localhost:8080/swagger-ui.html` para ver la documentación de Swagger generada a partir de su archivo
api.yml`.</string,>